4.1 Creating a Contact
A user creates a contact with a name (Jay Hamlin), email address (someone@example.com), and phone number ((206) 555-0123), and then saves it. The following is an example of what a client might do to accomplish the user's intentions, and the responses a server might return.
Before manipulating Contact objects, the client needs to ask the server to map property names or long IDs (LIDs) to property IDs by using the RopGetPropertyIdsFromNames ROP ([MS-OXCROPS] section 2.2.8.1).
Property |
Property set GUID |
LID |
---|---|---|
PidLidFileUnderList (section 2.2.1.1.13) |
{00062004-0000-0000-C000-000000000046} |
0x00008026 |
PidLidAutoLog (section 2.2.1.10.19) |
{00062004-0000-0000-C000-000000000046} |
0x00008025 |
PidLidAddressBookProviderEmailList (section 2.2.1.2.11) |
{00062004-0000-0000-C000-000000000046} |
0x00008028 |
PidLidAddressBookProviderArrayType section 2.2.1.2.12 |
{00062004-0000-0000-C000-000000000046} |
0x00008029 |
PidLidFileUnder (section 2.2.1.1.11) |
{00062004-0000-0000-C000-000000000046} |
0x00008005 |
PidLidFileUnderId (section 2.2.1.1.12) |
{00062004-0000-0000-C000-000000000046} |
0x00008006 |
PidLidContactCharacterSet (section 2.2.1.10.18) |
{00062004-0000-0000-C000-000000000046} |
0x00008023 |
PidLidEmail1DisplayName (section 2.2.1.2.1) |
{00062004-0000-0000-C000-000000000046} |
0x00008080 |
PidLidEmail1AddressType (section 2.2.1.2.2) |
{00062004-0000-0000-C000-000000000046} |
0x00008082 |
PidLidEmail1EmailAddress (section 2.2.1.2.3) |
{00062004-0000-0000-C000-000000000046} |
0x00008083 |
PidLidEmail1OriginalDisplayName (section 2.2.1.2.4) |
{00062004-0000-0000-C000-000000000046} |
0x00008084 |
PidLidEmail1OriginalEntryId (section 2.2.1.2.5) |
{00062004-0000-0000-C000-000000000046} |
0x00008085 |
For this example, the server returns the following property IDs in response to the RopGetPropertyIdsFromNames ROP request. The actual property IDs are at the discretion of the server.
Property |
Property ID |
---|---|
PidLidFileUnderList |
0x827B |
PidLidAutoLog |
0x8280 |
PidLidAddressBookProviderEmailList |
0x81D4 |
PidLidAddressBookProviderArrayType |
0x81D5 |
PidLidFileUnder |
0x8016 |
PidLidFileUnderId |
0x81DA |
PidLidContactCharacterSet |
0x8286 |
PidLidEmail1DisplayName |
0x 8013 |
PidLidEmail1AddressType |
0x81CE |
PidLidEmail1EmailAddress |
0x 8010 |
PidLidEmail1OriginalDisplayName |
0x801F |
PidLidEmail1OriginalEntryId |
0x81CF |
To create a Contact object, the client uses the RopCreateMessage ROP ([MS-OXCROPS] section 2.2.6.2). The server returns a success code and a handle to a Message object.
The properties of the Contact object are set according to data that is specified by the user. After the user has input the data for the Contact object, the client uses the RopSetProperties ROP ([MS-OXCROPS] section 2.2.8.6) to transmit the property settings to the server. The properties and their settings for this example are listed in the following table. The property types shown in the table are described in [MS-OXCDATA] section 2.11.1.
Property |
Property type |
Data |
Meaning |
---|---|---|---|
PidTagDisplayNamePrefix (section 2.2.1.1.3) |
PtypString |
|
|
PidTagSurname (section 2.2.1.1.4) |
PtypString |
|
|
PidTagMiddleName (section 2.2.1.1.5 |
PtypString |
|
|
PidTagGivenName (section 2.2.1.1.6) |
PtypString |
|
|
PidLidFileUnderList |
PtypMultipleInteger32 |
|
|
PidLidAddressBookProviderEmailList |
PtypMultipleInteger32 |
|
|
PidLidAddressBookProviderArrayType |
PtypInteger32 |
|
Email1 is defined |
PidLidFileUnder |
PtypString |
|
|
PidLidFileUnderId |
PtypInteger32 |
|
PidLidFileUnder is "<PidTagSurname>, <PidTagGivenName> <PidTagMiddleName>" |
PidTagGeneration (section 2.2.1.1.2) |
PtypString |
|
|
PidTagInitials (section 2.2.1.1.7) |
PtypString |
|
|
PidLidAutoLog |
PtypBoolean |
|
|
PidTagBusinessTelephoneNumber (section 2.2.4.21) |
PtypString |
|
|
PidLidContactCharacterSet |
PtypInteger32 |
|
|
PidTagDisplayName (section 2.2.1.1.8) |
PtypString |
|
|
PidLidEmail1DisplayName |
PtypString |
|
|
PidLidEmail1AddressType |
PtypString |
|
|
PidLidEmail1EmailAddress |
PtypString |
|
|
PidLidEmail1OriginalDisplayName |
PtypString |
|
|
PidLidEmail1OriginalEntryId |
PtypBinary |
|
|
PidTagRtfCompressed ([MS-OXCMSG] section 2.2.1.58.4) |
PtypBinary |
|
|
PidTagMessageClass (section 2.2.1.11.2) |
PtypString |
|
|
PidTagIconIndex ([MS-OXOMSG] section 2.2.1.10) |
PtypInteger32 |
|
|
PidTagSubjectPrefix ([MS-OXOMSG] section 2.2.1.60) |
PtypString |
|
|
PidTagSubject ([MS-OXPROPS] section 2.1034) |
PtypString |
|
|
When the user is ready to save his or her changes, the client uses the RopSaveChangesMessage ROP ([MS-OXCROPS] section 2.2.6.3) to commit the properties on the server.
The values of some properties will change during the execution of the RopSaveChangesMessage ROP; however, none of the properties that change are Contact object properties.