216-221.html

WindowsCE.[Essential Windows CE Application Programming].Jon Wiley & Son.zip

<FONT SIZE="-1">
<BR>
<I>(Publisher: John Wiley & Sons, Inc.)</I>
<BR>
Author(s): Robert Burdick
<BR>
ISBN: 0471327476
<BR>
Publication Date: 03/01/99
</FONT>
<P>
<form name="Search" method="GET" action="http://search.earthweb.com/search97/search_redir.cgi">

<INPUT TYPE="hidden" NAME="Action" VALUE="Search">
<INPUT TYPE="hidden" NAME="SearchPage" VALUE="http://search.earthweb.com/search97/samples/forms/srchdemo.htm">
<INPUT TYPE="hidden" NAME="Collection" VALUE="ITK">
<INPUT TYPE="hidden" NAME="ResultTemplate" VALUE="itk-simple-intrabook.hts">
<INPUT TYPE="hidden" NAME="ViewTemplate" VALUE="view.hts">

<font face="arial, helvetica" size=2><b>Search this book:</b></font><br>
<INPUT NAME="queryText" size=50 VALUE="">&nbsp;<input type="submit" name="submitbutton" value="Go!">
<INPUT type=hidden NAME="section_on" VALUE="on">
<INPUT type=hidden NAME="section" VALUE="http://www.itknowledge.com/reference/standard/0471327476/">

</form>


<!-- Empty Reference Subhead -->

<!--ISBN=0471327476//-->
<!--TITLE=Essential Windows CE Application Programming//-->
<!--AUTHOR=Robert Burdick//-->
<!--PUBLISHER=John Wiley & Sons, Inc.//-->
<!--IMPRINT=Wiley Computer Publishing//-->
<!--CHAPTER=7//-->
<!--PAGES=216-221//-->
<!--UNASSIGNED1//-->
<!--UNASSIGNED2//-->

<CENTER>
<TABLE BORDER>
<TR>
<TD><A HREF="214-216.html">Previous</A></TD>
<TD><A HREF="../ewtoc.html">Table of Contents</A></TD>
<TD><A HREF="221-220.html">Next</A></TD>
</TR>
</TABLE>
</CENTER>
<P><BR></P>
<P><FONT SIZE="+1"><B>Contacts Database Functions</B></FONT></P>
<P>The <I>ReadRecord</I> and <I>WriteRecord</I> functions in the phone list application were written as function wrappers that hide the internal details of the record data stored in the phone list database. In the same way, the contacts database functions work with AddressCards to allow the application programmer to think of contact information in a more natural way.</P>
<P>For example, to add a new record to the contacts database, an application calls <I>AddAddressCard</I>:</P>
<!-- CODE SNIP //-->
<PRE>
   AddAddressCard(pac, poidCard, pindex);
</PRE>
<!-- END CODE SNIP //-->
<P><I>pac</I> is a pointer to the AddressCard structure that contains the contact information to be added to the contacts database. <I>poidCard</I> is a pointer to a CEOID that is used by <I>AddAddressCard</I> to return the object identifier of the new record if it is successfully added to the contacts database. <I>pindex</I> is also a return value indicating the position index of the new record in the database.</P>
<P>In the phone list application example, <I>WriteRecord</I> always added a new phone list record that contained data for every property in the record. <I>AddAddressCard</I> is more generic in that it allows applications to add records with any subset of AddressCard properties. For this to work, an application must specify which properties are valid for the AddressCard to be added. This is done using the <I>SetMask</I> function:</P>
<!-- CODE SNIP //-->
<PRE>
   SetMask(pac, hhProp);
</PRE>
<!-- END CODE SNIP //-->
<P><I>pac</I> is again a pointer to an AddressCard structure. <I>hhProp</I> is any of the property tags defined for the contacts database. For example, to add an address card in which only the company and department fields are valid, an application would do the following:</P>
<!-- CODE //-->
<PRE>
   AddressCard ac;
   CEOID ceoid;
   int nIndex;
   memset(&#38;ac, 0, sizeof(AddressCard));
   ac.pszCompany = TEXT("Acme Widgets");
   ac.pszDepartment = TEXT("Bean Counting");
   SetMask(&#38;ac, HHPR_COMPANY_NAME);
   SetMask(&#38;ac, HHPR_DEPARTMENT_NAME);
   /Now we can add the card
   AddAddressCard(&#38;ac, &#38;ceoid, &#38;nIndex);*
</PRE>
<!-- END CODE //-->
<P>If all AddressCard properties are valid and are to be written to the database record, your application does not have to call <I>SetMask</I> for every property. Simply passing zero in the <I>hhProp</I> argument tells <I>SetMask</I> that all AddressCard properties are valid.</P>
<P>From our understanding of Windows CE databases, we can figure out what is going on inside <I>AddAddressCard</I>. <I>AddAddressCard</I> uses the mask prepared by the <I>SetMask</I> calls to know which values to extract from the AddressCard structure and which property identifiers to use to build up a CEPROPVAL array. As with any Windows CE database, all data read and write transactions ultimately boil down to reading and writing collections of CEPROPVAL structures.</P>
<P>Reading AddressCards is done with the <I>OpenAddressCard</I> function:</P>
<!-- CODE SNIP //-->
<PRE>
   OpenAddressCard(oidCard, pac, uFlags);
</PRE>
<!-- END CODE SNIP //-->
<P><I>oidCard</I> is the object identifier of the record to be read. <I>pac</I> is a pointer to an AddressCard structure into which <I>OpenAddressCard</I> places the contacts properties read from the specified record. <I>uFlags</I> can be either OAC_ALLOCATE or zero. OAC_ALLOCATE says that separate memory is allocated for each string property, and the strings are copied from the object store into the particular AddressCard fields. If an application needs to modify the properties in a record, this value must be set.</P>
<P>If <I>uFlags</I> is zero, memory is not allocated for the string properties, and the TCHAR* members of the AddressCard record returned by <I>OpenAddressCard</I> simply point to the string data in the database. This is the technique to use when the particular AddressCard record is not going to be modified by the application, but simply displayed in the application&#146;s user interface. Applications can also use the <I>GetAddressCardProperties</I> function to read records from the contacts database.</P>
<P><FONT SIZE="+1"><B>The Complete Contacts Database API</B></FONT></P>
<P>The contacts database API provides functions for opening and closing the contacts database, as well as reading, writing and modifying AddressCards. In addition, you can use the API to sort the database on the various AddressCard properties and enumerate AddressCards. The complete contacts database API is given in Table 7.5.
</P>
<TABLE WIDTH="100%" BORDER RULES="ROWS"><CAPTION ALIGN=LEFT><B>Table 7.5</B> The Contacts Database API
<TR>
<TH WIDTH="30%" ALIGN="LEFT">FUNCTION
<TH WIDTH="70%" ALIGN="LEFT">PURPOSE
<TR>
<TD>AddAddressCard
<TD>Adds an address card to the contacts database.
<TR>
<TD>CloseAddressBook
<TD>Closes the contacts database.
<TR>
<TD>CreateAddressBook
<TD>Creates the contacts database if it does not already exist.
<TR>
<TD>DeleteAddressCard
<TD>Deletes the specified address card from the contacts database.
<TR>
<TD>FreeAddressCard
<TD>Frees memory associated with an address card.
<TR>
<TD VALIGN="TOP">GetAddressCardIndex
<TD>Returns the position index of the specified address card in the contacts database.
<TR>
<TD VALIGN="TOP">GetAddressCardOid
<TD>Retrieves the object identifier of the address card as specified by its position index.
<TR>
<TD>GetAddressCardProperties
<TD>Gets the properties of an address card.
<TR>
<TD VALIGN="TOP">GetColumnProperties
<TD>Retrieves the property tags corresponding to the columns by which the contacts database can be sorted.
<TR>
<TD VALIGN="TOP">GetMatchingEntry
<TD>Searches the contacts database for an address card with a name property containing the specified search string.
<TR>
<TD>GetNumberOfAddressCards
<TD>Returns the number of address cards in the contacts database.
<TR>
<TD VALIGN="TOP">GetPropertyDataStruct
<TD>Retrieves a PropertyDataStruct for a specified contacts database property.
<TR>
<TD>GetSortOrder
<TD>Returns the current contacts database sort order.
<TR>
<TD>ModifyAddressCard
<TD>Changes the contents of an address card.
<TR>
<TD>OpenAddressBook
<TD>Opens the contacts database if it exists.
<TR>
<TD VALIGN="TOP">RecountCards
<TD>Counts the number of address cards. This is necessary if another application modifies the contacts database while your application has it open.
<TR>
<TD>SetColumnProperties
<TD>Specifies the properties on which the contacts database can be sorted.
<TR>
<TD>SetMask
<TD>Specifies which properties are assigned in an address card.
<TR>
<TD>SetSortOrder
<TD>Sets the contacts database sort order.
</TABLE>
<P><BR></P>
<CENTER>
<TABLE BORDER>
<TR>
<TD><A HREF="214-216.html">Previous</A></TD>
<TD><A HREF="../ewtoc.html">Table of Contents</A></TD>
<TD><A HREF="221-220.html">Next</A></TD>
</TR>
</TABLE>
</CENTER>


<!-- all of the reference materials (books) have the footer and subfoot reveresed -->
<!-- reference_subfoot = footer -->
<!-- reference_footer = subfoot -->

<!-- BEGIN SUB FOOTER -->
		<br><br>
		</TD>
    </TR>
	</TABLE>

		
	<table width="640" border=0 cellpadding=0 cellspacing=0>
		<tr>
		<td align="left" width=135><img src="/images/white.gif" width=100 height="1" alt="" border="0"></td>
		
		
<!-- END SUB FOOTER -->

<!-- all of the books have the footer and subfoot reveresed -->
<!-- reference_subfoot = footer -->
<!-- reference_footer = subfoot -->

<!-- FOOTER -->
			
		<td width="515" align="left" bgcolor="#FFFFFF">
<font face="arial, helvetica" size="1"><b><a href="/products.html"><font color="#006666">Products</font></a>&nbsp;|&nbsp; <a href="/contactus.html"><font color="#006666">Contact Us</font></a>&nbsp;|&nbsp; <a href="/aboutus.html"><font color="#006666">About Us</font></a>&nbsp;|&nbsp; <a href="http://www.earthweb.com/corporate/privacy.html" target="_blank"><font color="#006666">Privacy</font></a> &nbsp;|&nbsp; <a href="http://www.itmarketer.com/" target="_blank"><font color="#006666">Ad Info</font></a> &nbsp;|&nbsp; <a href="/"><font color="#006666">Home</font></a></b>
		<br><br>
		
		Use of this site is subject to certain <a href="/agreement.html">Terms &amp; Conditions</a>, <a href="/copyright.html">Copyright &copy; 1996-1999 EarthWeb Inc.</a><br> 
All rights reserved.  Reproduction whole or in part in any form or medium without express written permision of EarthWeb is prohibited.</font><p>
</td>
		</tr>
</table>
</BODY>
</HTML>

<!-- END FOOTER -->