Windows Mobile poom

Poom operations: icontact, iItem, ipoutlookitemcollection, ipoutlookapp operations

I. Basic Knowledge
Poom is a set of COM interface libraries based on Microsoft COM technology for personal information management on mobile phones (PIM. Therefore, in addition to being familiar with the basic technologies of mobile development, developers must also be familiar with the COM technology and understand the basic methods of using COM. For more information about com, see related com books. I think the following concepts must be mastered:
1. COM Initialization and uninstallation
2. Interface query and Acquisition
3. String operations in COM
4. Use isteam (it will be used later when operating the contact photo)

II. Introduction to the poom object interface class
Poom not only includes operations on contacts, but also includes tasks, appointment reminders, and other personal information management content. The SDK clearly shows various COM object interfaces such as itask, icontact, and iappointment. This article describes various contact-related interfaces:
Ipoutlookapp
All poom operations must first come to the corresponding operation interface through it. getitemfromoid is useful in its method functions. This function can be uniquely identified by OID ), the corresponding object interface is displayed. The following shows its application. The upgraded version ipoutlookapp2 is available on wm5.
Oid (unique identifier): uniquely identifies a record in the WM system, that is, a contact we are familiar with, a appointment, and they have a unique identifier in the system, they are stored in the system database.
Ifolder
In poom, the contacts, tasks, and appointments objects exist as folders. Therefore, we need to use it to access the itask, icontact, and iappointment object interfaces. For example, we have a folder for landscape photos, which contains all landscape photos. We also have a folder for characters, which contains photos of all characters. We will use its get_items method function.
Ipoutlookitemcollection
To further access the icontact object interface, you must obtain the set of each record from ifolder and access each record through the set.
IItem
It refers to a common record in Pim. Each record can be implemented through the iItem object interface, which does not distinguish between categories (tasks, contacts, and appointment are treated the same). The following describes in detail.

Icontact
This article mainly uses the object interface for handling contact information. Here I want to point out (maybe I did not find it). After wm5, it provided about 10 new content, but it was not provided in this object interface, however, iItem can be used for processing.

Brief Introduction to several other object interfaces
Itask: If you need to process task information, use it (no specific use)
Iappointment: when processing the appointment information, you can use it with irecurrencepattern to process the cycle information of the appointment.
3. How to Use poom
1. initialize and open poom
Poom is based on the COM technology, so coinitializeex must be used to initialize COM objects. Do not forget to call couninitialize () to uninstall poom.
After initializing COM, you can use some basic interface functions of COM. You can use cocreateinstance to obtain the poom application object. After obtaining the application object, you must log on to poom-to establish a dialog process with the poom system. Therefore, after this poom operation is used up or not required, you need to exit this session.

Hresult hr;
Ipoutlookapp * m_polapp;
If (succeeded (coinitializeex (null, 0) // initialize com
{
// Obtain the ipoutlookapp object
If (succeeded (cocreateinstance (clsid_application, null, clsctx_inproc_server,
Iid_ipoutlookapp, reinterpret_cast <void **> (& m_polapp )))){
If (failed (m_polapp-> Logon (null) {// creates a session
If (m_polapp)
M_polapp-> release ();
Return false ;}
} Else
Return false;
}
...................
...................
If (m_polapp ){
M_polapp-> logoff (); end session
M_polapp-> release (); release
M_polapp = NULL;
}
Couninitialize (); // release com

2. Obtain a type of contact information
This article mainly discusses the contact content of poom, so here we use the contact content to demonstrate specific poom operations. Of course, you can operate tasks or appointment.
What should I do next after opening the poom?
First, you must select what type of operation is required. What kind of operation is a contact? Or task and appointment reminders? As mentioned above, we need to select a folder and use it to access our specific operations. You can use the getdefaultfolder method to obtain a folder.
Then, call the get_items method to obtain an ipoutlookitemcollection interface:
M_pfolder-> get_items (& m_pitems)
Through the set interface, you can obtain the number of records contained in the folder. The common point is the number of contacts, tasks, and appointments. You can also find many useful methods: Query and sorting. Which of the following information is most useful for simple operations.
The complete code is as follows:

If (succeeded (m_polapp-> getdefaultfolder (olfoldercontacts, & m_pfolder )))
If (succeeded (m_pfolder-> get_items (& m_pitems )))
If (succeeded (m_pitems-> get_count (& m_itemcount )))
Return true;

3. Perform icontact and iItem object operations
A. icontact operation
The reader may be a little impatient, but he hasn't seen how to get the contact details. It will be displayed immediately.
You can use the item method of the ipoutlookitemcollection interface to obtain an icontact object interface.
If (failed (m_pitems-> item (index, reinterpret_cast <idispatch **> (& pcontact ))))
{
Return false;
}
It can be found that the main parameter is the index value of an index. The ipoutlookitemcollection set uses an index to locate a specific contact record. With the icontact interface, you can easily obtain the required contact information. You can use the delete method of the icontact object interface to delete records.
Note that if a record in the middle is deleted, the record corresponding to the index value changes so that it does not match. The best way is to start deleting from the back.
For example:
Name:
BSTR pbstrbuf = NULL;
Pcontact-> get_firstname (& pbstrbuf );
Pcontact-> get_middlename (& pbstrbuf );
Pcontact-> get_lastname (& pbstrbuf );
Get the mobile phone number:
Pcontact-> get_mobiletelephonenumber (& pbstrbuf );
Birthday:
Date mdate
Pcontact-> get_birthday (& mdate );
The icontact document details the content of all methods.
Do not forget to release the com string pbstrbuf memory. Call the following function:
Sysfreestring (pbstrbuf );
If you know how to get the information, you also need to know how to write the information. Writing information using icontact is as convenient as calling the put _ ××× method. Finally, do not forget to save the call:
Pcontact-> Save ();
If you forget to call it, it will be a waste of time.

B. iItem operation
If you have a wm5 mobile phone in your hand, you will find "nickname, instant message, company phone number" and other information contained on wm5, how can I not find the corresponding method in icontact? (If anyone is familiar with it and can find it, please tell me, thank you )? If you ask me why, I can only say that I don't know. Fortunately, there are still iItems, but don't forget the iItem object interface mentioned above. poom also provides a comprehensive iItem object interface method.
IItem provides a complete processing interface, but its ease of use is also reduced. The iItem interface provides getprops and setprops, which are an encapsulation of PIM database operations. If you are familiar with database operations, you will find that they are very similar. See how to use getprops to obtain data.
Int dwlen = 0;
Hresult hr;
Ulong cbbuffer = 0;
Cepropid rgpropid [1];
Cepropval * Buf = NULL;
Handle hheap = getprocessheap ();
Rgpropid [0] = pimpr_nickname;
HR = pitem-> getprops (rgpropid, cedb_allowrealloc, 1, & Buf, & cbbuffer, hheap );
If (failed (HR) | 0 = cbbuffer | Buf = NULL)
Return 0;
Else
{Cepropval * ppropval = Buf;
If (ppropval [0]. wflags! = Cedb_propnotfound)
{
If (loword (ppropval [0]. propid) = cevt_lpwstr)
Outputdebugstring (ppropval [0]. Val. lpwstr );
}
Else
Dwlen = 0;
Localfree (BUF );
Heapfree (hheap, 0, Buf );
}
Readers may have a headache, but it is much more complicated than icontact. However, if you are familiar with database operations, it is still not difficult. I will briefly introduce some database operation concepts.
Getprops has two modes: poom allocates memory by itself, and caller provides memory allocation. Here I have the former, so I need to provide a heap handle and use getprocessheap to create it.
Cepropid rgpropid [1] provides the information that the caller needs to obtain and uses it to determine what data (such as name, number, and address) is returned by getprops ). The above Code uses pimpr_nickname to obtain the nickname information. Cedb_propnotfound is used to determine whether this information exists. Do not ignore this because the database format determines that this situation does occur, rather than giving you an empty string.
Compared with the write operation, the setprops method provided by iItem is much simpler. You only need to specify the data and call save to save the data.
Cepropval rgpropval [1] = {0 };
Rgpropval [0]. propid = pimpr_nickname;
Rgpropval [0]. Val. lpwstr = _ T ("Jun ");
HR = pitem-> setprops (0, 1, rgpropval );
If (succeeded (HR ))
HR = pitem-> Save ();

C. Photo-Special Data Processing
There is a special information type in the contact information-stream type data. Wm5 provides the contact photo function. Its data is stored in stream mode. If you are familiar with the database, you will find that it is actually stored in blob binary mode and the database, because the database does not have the stream type. Here we use the iItem openproperty method to store photos.
Hresult hR = e_fail;
Istream * pstream = NULL;
Cepropid propid = pimpr_picture;
Ulong cbread = 0;
If (succeeded (hR = pitem-> openproperty (propid, generic_read, & pstream )))
{HR = pstream-> Read (pserial, buflen, & cbread );
Pstream-> release ();}
If (succeeded (HR) return cbread;
Corresponding write operations:
If (succeeded (hR = pitem-> openproperty (propid, generic_write, & pstream )))
{HR = pstream-> write (pserial, buflen, & cbwritten );
If (succeeded (HR ))
{HR = pstream-> commit (0 );
HR = pitem-> Save ();}
Pstream-> release ();}
}
The above Code uses the istream interface to read and write data. Do not forget to call the commit method of istream and the Save method of iItem to save data after writing.

4. usage tips of OID
The concepts of OID have been explained above. In poom, oId is a very important concept and the get_oid method is found in many interfaces. Because the oId is a unique identifier, it remains unchanged. Therefore, we can use this feature to save it, instead of making sense at the next runtime like the memory address. In some applications, when you need to operate (modify, delete) the record that has been accessed again, you do not need to use a silly specific value search to locate it, you can directly use the saved OID for processing.
First, call the corresponding get_oid
Long OID
Icontact * pcontact; // assume this interface has been obtained.
Pcontact-> get_oid (& OID );
Save the oId to a valid space. When you need to process this record but cannot obtain the pcontact interface, you can call the getitemfromoid method of ipoutlookapp to directly obtain icontact:
Icontact * pcontact = NULL;
If (s_ OK = m_polapp-> getitemfromoid (OID, reinterpret_cast <idispatch **> (& pcontact )))
{...... }

5. Post-processing-save data
According to the above process, you can obtain all the contact information. Next, you can use file IO-related operations to save the data to the file. The specific discussion is not within the scope of this article. When restoring the backup data, file IO is performed first and then poom is performed, which is described in detail above.

Iv. Conclusion
This article describes how to use poom and contact-related object interfaces to read or write various contact information. I hope that the readers of this Article can understand other poom operations (task and appointment). It would be better to use poom more deeply.
The rush of time, coupled with my own learning skills, will inevitably lead to mistakes in the text, you are welcome to correct.