pimlist.html

J2ME PDA开发PIM的技术规范,可使应用程序查看手机本地联系人列表, 本地文件

								A null category string is equivalent to the category string <code>UNCATEGORIZED</code>.
							<li>
								An empty category string <code>""</code>
							is considered a valid string parameter for comparison with existing categories, 
							e.g. "" matches only a category also named "".
							<li>
								The full category string is used for comparison, and must return true for an <code>String.equals()</code>
								comparison.</li>
						</ul>
					<P>
					</P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>category</CODE> - A string category to find matching 
									items with. <DT><B>Returns:</B><DD>An enumeration of all items in the PIM list that 
											match the category. <DT><B>Throws:</B>
												<DD>
													<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
													- If an error occurs or the list is no longer accessible or closed.
													<DD>
														<CODE>java.lang.SecurityException</CODE> - If the application is not given 
														permission to read the PIM list or the list is opened WRITE_ONLY.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="getCategories()"><!-- --></A><H3>
				getCategories</H3>
			<PRE>
public java.lang.String[] <B>getCategories</B>()
                                 throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
			<DL>
				<DD>
					Returns the categories defined for the PIM list. If there are no categories 
					defined for the PIM list or categories are unsupported for the list, then a 
					zero length array is returned.
					<P></P>
					<DD>
						<DL>
							<DT><B>Returns:</B><DD>A string array containing the categories defined for the PIM 
									list. <DT><B>Throws:</B>
										<DD>
											<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
											- If an error occurs or the list is no longer accessible or closed.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="isCategory(java.lang.String)"><!-- --></A><H3>
				isCategory</H3>
			<PRE>
public boolean <B>isCategory</B>(java.lang.String&nbsp;category)
                   throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
			<DL>
				<DD>
					Returns indication of whether the given category is a valid existing category 
					for this list.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String representing the category to 
									query for. <DT><B>Returns:</B><DD>true if the category indicated is a valid existing 
											category for this list, false otherwise. <DT><B>Throws:</B>
												<DD>
													<CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is <code>null</code>.
													<DD>
														<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
														- If an error occurs or the list is no longer accessible or closed.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="addCategory(java.lang.String)"><!-- --></A><H3>
				addCategory</H3>
			<PRE>
public void <B>addCategory</B>(java.lang.String&nbsp;category)
                 throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
			<DL>
				<DD>
					Adds the provided category to the PIM list. If the given category already 
					exists for the list, the method does not add another category and considers 
					that this method call is successful and returns.
					<P></P>
					<P>
						The category names are case sensitive in this API, but not necessarily in the 
						underlying implementation. For example, "Work" and "WORK" map to the same 
						underlying category if the platform's implementation of categories is 
						case-insensitive; adding both separately would result in only one category 
						being created in this case.
					</P>
					<P>
					A string with no characters ("") may or may not be a valid category on a 
					particular platform. If the string is not a valid category as defined by the 
					platform, a PIMException is thrown when trying to add it.
					<P>
					</P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String representing a category to 
									add. <DT><B>Throws:</B>
										<DD>
											<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
											- If categories are unsupported, an error occurs, or the list is no longer 
											accessible or closed. Also returned if the max number of categories for this 
											list is exceeded, or if the category name is invalid.
											<DD>
												<CODE>java.lang.SecurityException</CODE> - if the application is not given 
												permission to write to the PIM list or the list is opened READ_ONLY.
												<DD>
													<CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is <code>null</code>.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="deleteCategory(java.lang.String, boolean)"><!-- --></A><H3>
				deleteCategory</H3>
			<PRE>
public void <B>deleteCategory</B>(java.lang.String&nbsp;category,
                           boolean&nbsp;deleteUnassignedItems)
                    throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
			<DL>
				<DD>
					Deletes the indicated category from the PIM list. If the indicated category is 
					not in the PIM list, this method is treated as successfully completing.
					<p>
					The category names are case sensitive in this API, but not necessarily in the 
					underlying implementation. For example, "Work" and "WORK" map to the same 
					underlying category if the platform's implementation of categories is 
					case-insensitive; removing both separately would result in only one category 
					being removed in this case.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String category.<DD><CODE>deleteUnassignedItems</CODE>
										- boolean flag where true indicates to delete items that no longer have any 
										categories assigned to them as a result of this method, and where false 
										indicates that no items are deleted as a result of this method. <DT><B>Throws:</B>
											<DD>
												<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
												- If categories are unsupported, an error occurs, or the list is no longer 
												accessible or closed.
												<DD>
													<CODE>java.lang.SecurityException</CODE> - if the application is not given 
													permission to write to the PIM list or the list is opened READ_ONLY.
													<DD>
														<CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is <code>null</code>.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="renameCategory(java.lang.String, java.lang.String)"><!-- --></A><H3>
				renameCategory</H3>
			<PRE>
public void <B>renameCategory</B>(java.lang.String&nbsp;currentCategory,
                           java.lang.String&nbsp;newCategory)
                    throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
			<DL>
				<DD>
					Renames a category from an old name to a new name. All items associated with 
					the old category name are changed to reference the new category name after this 
					method is invoked. If the new category name is already an existing category, 
					then the items associated with the old category name are associated with the 
					existing category.
					<P></P>
					<P>
					A string with no characters ("") may or may not be a valid category on a 
					particular platform. If the string is not a category on a platform, a 
					PIMException is thrown when trying to rename a category to it.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>currentCategory</CODE> - String representing the 
									current category name.<DD><CODE>newCategory</CODE> - String representing the new 
										category name to use. <DT><B>Throws:</B>
											<DD>
												<CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE>
												- If categories are unsupported, an error occurs, the list is no longer 
												accessible or closed, or the category name is invalid.
												<DD>
													<CODE>java.lang.SecurityException</CODE> - if the application is not given 
													permission to write to the PIM list or the list is opened READ_ONLY.
													<DD>
														<CODE>java.lang.NullPointerException</CODE> - if <code>currentCategory</code> or
														<code>newCategory</code> is <code>null</code>.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="maxCategories()"><!-- --></A><H3>
				maxCategories</H3>
			<PRE>
public int <B>maxCategories</B>()</PRE>
			<DL>
				<DD>
					Returns the maximum number of categories that this list can have.
					<P></P>
					<DD>
						<DL>
							<DT><B>Returns:</B><DD>int the number of categories supported by this list. 0 indicates 
									no category support and -1 indicates there is no limit the the number of 
									categories that this list can have.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="isSupportedField(int)"><!-- --></A><H3>
				isSupportedField</H3>
			<PRE>
public boolean <B>isSupportedField</B>(int&nbsp;field)</PRE>
			<DL>
				<DD>
					Indicates whether or not the given field is supported in this PIM list.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field to check, as defined by in the 
									class implementing the PIMItem. <DT><B>Returns:</B><DD>true if supported in this list, 
											false otherwise. Invalid fields return false.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="getSupportedFields()"><!-- --></A><H3>
				getSupportedFields</H3>
			<PRE>
public int[] <B>getSupportedFields</B>()</PRE>
			<DL>
				<DD>
					Gets all fields that are supported in this list. All fields supported by this 
					list, including both standard and extended, are returned in this array.
					<P></P>
					<DD>
						<DL>
							<DT><B>Returns:</B><DD>an int array containing all fields supported by this list. The 
									order of the fields returned is unspecified. If there are no supported fields, 
									a zero-length array is returned.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="isSupportedAttribute(int, int)"><!-- --></A><H3>
				isSupportedAttribute</H3>
			<PRE>
public boolean <B>isSupportedAttribute</B>(int&nbsp;field,
                                    int&nbsp;attribute)</PRE>
			<DL>
				<DD>
					Indicates whether or not the given attribute is supported in this PIM list for 
					the indicated field.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field against which the attribute is 
									checked.<DD><CODE>attribute</CODE> - The single attribute to check <DT><B>Returns:</B><DD>true 
												if supported, false otherwise. Invalid fields and invalid attributes return 
												false.</DD></DL>
					</DD>
			</DL>
			<HR>
			<A NAME="getSupportedAttributes(int)"><!-- --></A><H3>
				getSupportedAttributes</H3>
			<PRE>
public int[] <B>getSupportedAttributes</B>(int&nbsp;field)</PRE>
			<DL>
				<DD>
					Returns an integer array containing all of the supported attributes for the 
					given field. All attributes supported by this list, including both standard and 
					extended, are returned in this array. The attributes are provided one attribute 
					per entry in the returned integer array.
					<P></P>
					<DD>
						<DL>
							<DT><B>Parameters:</B><DD><CODE>field</CODE> - the field to check <DT><B>Returns:</B><DD>an int 
											array of the supported attributes, one attribute per entry in the array. If 
											there are no supported fields, a zero-length array is returned. <DT><B>Throws:</B>
												<DD>
													<CODE>java.lang.IllegalArgumentException</CODE> - if field is not a valid field 
													(i.e. not a standard field and not an extended field). IllegalArgumentException 
													takes precedence over UnsupportedFieldException when checking the provided 
													field.
													<DD>
														<CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE>
														- if the field is not supported in the implementing instance of the class.</DD></DL>
					</DD>