pim.html

J2ME手机编程规范JSR-75文档

 <A HREF="../../../javax/microedition/pim/PIM.html#listPIMLists(int)"><CODE>listPIMLists(int)</CODE></A> can be used to open a list.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>pimListType</CODE> - int representing the PIM list type to open, either
           <A HREF="../../../javax/microedition/pim/PIM.html#CONTACT_LIST"><CODE>CONTACT_LIST</CODE></A>, <A HREF="../../../javax/microedition/pim/PIM.html#EVENT_LIST"><CODE>EVENT_LIST</CODE></A>, or <A HREF="../../../javax/microedition/pim/PIM.html#TODO_LIST"><CODE>TODO_LIST</CODE></A>.<DD><CODE>mode</CODE> - in which the List is opened, either
           <A HREF="../../../javax/microedition/pim/PIM.html#READ_ONLY"><CODE>READ_ONLY</CODE></A>, <A HREF="../../../javax/microedition/pim/PIM.html#READ_WRITE"><CODE>READ_WRITE</CODE></A>, or <A HREF="../../../javax/microedition/pim/PIM.html#WRITE_ONLY"><CODE>WRITE_ONLY</CODE></A>.<DD><CODE>name</CODE> - the named List to open
<DT><B>Returns:</B><DD>the named List.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If the list is not available, the operation is
           unsupported or an error occurs.
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
           permission that matches the requested mode.
<DD><CODE>java.lang.IllegalArgumentException</CODE> - If an invalid mode is provided as a
           parameter or if pimListType is not a valid
           PIM list type.
<DD><CODE>java.lang.NullPointerException</CODE> - If <code>name</code> is <code>null</code>.</DL>
</DD>
</DL>
<HR>

<A NAME="listPIMLists(int)"><!-- --></A><H3>
listPIMLists</H3>
<PRE>
public abstract java.lang.String[] <B>listPIMLists</B>(int&nbsp;pimListType)</PRE>
<DL>
<DD>Returns a list of all PIM List names for the given PIM list type.  If
 there are no Lists for that list type, a zero length String array is
 returned.  The first name in the list is the name of the default List for
 a type.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>pimListType</CODE> - int representing the PIM list type to list, either
           <A HREF="../../../javax/microedition/pim/PIM.html#CONTACT_LIST"><CODE>CONTACT_LIST</CODE></A>, <A HREF="../../../javax/microedition/pim/PIM.html#EVENT_LIST"><CODE>EVENT_LIST</CODE></A>, or <A HREF="../../../javax/microedition/pim/PIM.html#TODO_LIST"><CODE>TODO_LIST</CODE></A>.
<DT><B>Returns:</B><DD>a list of named Lists
<DT><B>Throws:</B>
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
           permission to read PIM lists.
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if pimListType is not a valid
           PIM list type.</DL>
</DD>
</DL>
<HR>

<A NAME="fromSerialFormat(java.io.InputStream, java.lang.String)"><!-- --></A><H3>
fromSerialFormat</H3>
<PRE>
public abstract <A HREF="../../../javax/microedition/pim/PIMItem.html">PIMItem</A>[] <B>fromSerialFormat</B>(java.io.InputStream&nbsp;is,
                                           java.lang.String&nbsp;enc)
                                    throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A>,
                                           java.io.UnsupportedEncodingException</PRE>
<DL>
<DD>Creates and fills one or more PIM items from data provided in the given
 InputStream object where the data is expressed in a valid
 data format supported by this platform. The character
 stream starting from the InputStream's current character position must
 respresent a complete entry as specified by the supported data format or
 else a <A HREF="../../../javax/microedition/pim/PIMException.html"><CODE>PIMException</CODE></A> is thrown.
 This method reads only one complete data entry from the
 InputStream, leaving the InputStream object open and its character
 position on the character after the end of the entry.  The single data
 entry in the InputStream will result in the creation of 1 or more PIMItems
 (in some data formats more than one PIMItem may be in a single entry).
 </P><P>
 The format of the data in the InputStream determines what type of PIM
 items are created (see <A HREF="../../../javax/microedition/pim/PIM.html#supportedSerialFormats(int)"><CODE>supportedSerialFormats(int)</CODE></A> to see what
 data formats are supported by this implementation).
 </P><P>
 It is the responsibility of the application to perform
 any transfer character decoding (such as <i>Content-Transfer-Encoding</i>
 for MIME or <i>Transfer-Encoding</i> for HTTP) prior to providing the
 InputStream object with the entry data to this method.
 </P><P>
 In creating PIM items, data from the input stream is taken and mapped to
 appropriate corresponding PIM item fields. If there is no appropriate
 corresponding PIM item field for a particular piece of data in the input
 stream, that data may be either silently discarded by this method or
 retained in the PIM item as an extended field value (the action taken is
 implementation specific).  If the data from the input stream does not
 contain values for all of the fields required by the item, the VM may
 provide default values so that the information can still be received
 and PIMItems can still be created.
 </P><P>
 Also note that creation of the PIM items does not add the item to
 any list; the import method for a list capable of containing the specific
 PIM item must be used to add the item to a list.  For
 example, should a <code>Contact</code> item be created, then the method
 <code>ContactList.importContact</code> should be invoked from an existing
 list to import that contact into the target list.</P>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>is</CODE> - an input stream containing PIM information in a well-known
           data format supported by this method.<DD><CODE>enc</CODE> - the character encoding of the characters in the input
           stream.  If <code>null</code>, the default character encoding
           of UTF-8 is used.
<DT><B>Returns:</B><DD>an array of newly created PIM items created from the
           OutputStream.  In some cases, more than one PIM item may be
           created from a complete entry (for example, a single vCalendar
           entry may produce two PIM items, both an Event and a ToDo).
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If the data is incorrect or does not contain
           enough information to form a complete entry.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>is</code> is
           <code>null</code>.
<DD><CODE>java.io.UnsupportedEncodingException</CODE> - if <code>enc</code> is not a
           encoding method supported on this platform.<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/pim/PIM.html#supportedSerialFormats(int)"><CODE>supportedSerialFormats(int)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="toSerialFormat(javax.microedition.pim.PIMItem, java.io.OutputStream, java.lang.String, java.lang.String)"><!-- --></A><H3>
toSerialFormat</H3>
<PRE>
public abstract void <B>toSerialFormat</B>(<A HREF="../../../javax/microedition/pim/PIMItem.html">PIMItem</A>&nbsp;item,
                                    java.io.OutputStream&nbsp;os,
                                    java.lang.String&nbsp;enc,
                                    java.lang.String&nbsp;dataFormat)
                             throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A>,
                                    java.io.UnsupportedEncodingException</PRE>
<DL>
<DD>Writes the data from the given item to the given OutputStream object as
 Unicode characters in a format indicated by the String parameter.  The
 character encoding for those characters written to the OutputStream is in
 the provided character encoding.
 The data format specified must be supported by the PIM implementation
 (see <A HREF="../../../javax/microedition/pim/PIM.html#supportedSerialFormats(int)"><CODE>supportedSerialFormats(int)</CODE></A>) or else an
 <code>IllegalArgumentException</code> is thrown. After this method is
 invoked, the OutputStream will contain the contact as a data stream in
 the given data format.  The output produced is a single complete entry
 and suitable for exchange with other programs supporting that data format.
 The OutputStream is left open and any writes to that stream will occur
 immediately after the entry just written.
 </P><P>
 All data fields contained in the provided PIMItem are written out to the
 output stream in the specified format.  Fields that do not have specific
 corresponding fields in the data format specified will be written as
 extended fields if the data format supports extended fields.
 </P><P>
 It is the responsibility of the application to perform any further
 character encoding needed for transportation of the vCard entry (such as
 <i>Content-Transfer-Encoding</i> for MIME or <i>Transfer-Encoding</i>
 for HTTP).
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>item</CODE> - the item to export to the OutputStream object<DD><CODE>os</CODE> - the OutputStream object that this item is written to as
          a character stream.<DD><CODE>enc</CODE> - the character encoding used to write the PIMItem to the
          OutputStream.  If <code>null</code>, the default character
          encoding of UTF-8 is used.<DD><CODE>dataFormat</CODE> - the requested PIM data format to use (i.e. the
          well-known structure of the data prior to character encoding)
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - if an error occurs when coverting the item's
          data, preventing the data from completely being written.
          There is no guarantee that the OutputStream will be unmodified
          or contain incomplete information if this exception is thrown.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>os</code> is <code>null</code>,
          <code>dataFormat</code> is <code>null</code>, or
          <code>item</code> is <code>null</code>.
<DD><CODE>java.io.UnsupportedEncodingException</CODE> - if <code>enc</code> is not a
          encoding method supported on this platform.<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/pim/PIM.html#supportedSerialFormats(int)"><CODE>supportedSerialFormats(int)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="supportedSerialFormats(int)"><!-- --></A><H3>
supportedSerialFormats</H3>
<PRE>
public abstract java.lang.String[] <B>supportedSerialFormats</B>(int&nbsp;pimListType)</PRE>
<DL>
<DD>This method returns the supported data formats for items
 used when converting a PIMItem's data to and from data streams.
 The return value is suitable for use as the data format parameter in
 <A HREF="../../../javax/microedition/pim/PIM.html#toSerialFormat(javax.microedition.pim.PIMItem, java.io.OutputStream, java.lang.String, java.lang.String)"><CODE>toSerialFormat(javax.microedition.pim.PIMItem, java.io.OutputStream, java.lang.String, java.lang.String)</CODE></A>. The naming convention for the strings returned
 is the common name of the data format in all capital letters, followed
 by a slash ("/"), and then followed by the version number of the data
 format. For example "VCARD/2.1" or "VCALENDAR/1.0".
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>pimListType</CODE> - int representing the PIM list type, either
           <A HREF="../../../javax/microedition/pim/PIM.html#CONTACT_LIST"><CODE>CONTACT_LIST</CODE></A>, <A HREF="../../../javax/microedition/pim/PIM.html#EVENT_LIST"><CODE>EVENT_LIST</CODE></A>, or <A HREF="../../../javax/microedition/pim/PIM.html#TODO_LIST"><CODE>TODO_LIST</CODE></A>.
<DT><B>Returns:</B><DD>String array of data formats supported for converting
           items to and from data streams.
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if pimListType is not a valid
           PIM list type.</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
Proposed Final Draft<br>Rev. 0.24</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV CLASS&nbsp;
&nbsp;<A HREF="../../../javax/microedition/pim/RepeatRule.html"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="PIM.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;
<SCRIPT>
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;<A HREF="#field_summary">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;<A HREF="#field_detail">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<font size=-1>Copyright &copy; 2002-2003 PalmSource, Inc.  All Rights Reserved.<br>Java is a trademark of Sun Microsystems, Inc.</font>
</BODY>
</HTML>