4.1 Creating a Contact

  • Article

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 

 00   00

 ""

PidTagSurname (section 2.2.1.1.4)

PtypString 

 48   00 61 00 6D 00 6C 00 69 00 6E 00 00 00

 "Hamlin"

PidTagMiddleName (section 2.2.1.1.5

PtypString 

 00   00

 ""

PidTagGivenName (section 2.2.1.1.6)

PtypString 

 4A   00 61 00 79 00 00 00

 "Jay"

PidLidFileUnderList

PtypMultipleInteger32 

 05   00 00 00 
 17   80 00 00 
 37   80 00 00 
 16   3A 00 00 
 19   80 00 00 
 18   80 00 00

 cValues:   0x00000005 
 lpl:   {0x00008017; 
 0x00008037;   
 0x00003A16;   
 0x00008019;   
 0x00008018}

PidLidAddressBookProviderEmailList

PtypMultipleInteger32 

 01   00 00 00 
 00   00 00 00

 cValues:   0x00000001
 lpl:   {0x00000000}

PidLidAddressBookProviderArrayType

PtypInteger32 

 0x00000001

Email1 is defined

PidLidFileUnder

PtypString 

 48   00 61 00 6D 00 6C 00 69 00 6E 00 2C 00 20 00 4A 00 61 00 79 00 00 00

 "Hamlin,   Jay"

PidLidFileUnderId

PtypInteger32 

 0x00008017

PidLidFileUnder is "<PidTagSurname>, <PidTagGivenName> <PidTagMiddleName>"

PidTagGeneration (section 2.2.1.1.2)

PtypString 

 00   00

 ""

PidTagInitials (section 2.2.1.1.7)

PtypString 

 4A   00 2E 00 48 00 2E 00
 00   00

 "J.H."

PidLidAutoLog

PtypBoolean 

 0x00

 FALSE

PidTagBusinessTelephoneNumber (section 2.2.4.21)

PtypString 

 28   00 32 00 30 00 36 00 29 00 20 00 35 00 35 00 35 00 2D 00 30 00 31 00 32 00 33   00 00 00

 (206)   555-0123"

PidLidContactCharacterSet

PtypInteger32 

 0x00000100

US character set

PidTagDisplayName (section 2.2.1.1.8)

PtypString 

 4A   00 61 00 79 00 20 00 48 00 61 00 6D 00 6C 00 69 00 6E 00 00 00

 "Jay   Hamlin"

PidLidEmail1DisplayName

PtypString 

 73   00 6F 00 6D 00 65 00 6F 00 6E 00 65 00 20 00 28 00 73 00 6F 00 6D 00 65 00 6F   00 6E 00 65 00 40 00 65 00 78 00 61 00 6D 00 70 00 6C 00 65 00 2E 00 63 00 6F   00 6D 00 29 00 00 00

 "someone   (someone@example.com)"

PidLidEmail1AddressType

PtypString 

 45   00 58 00 00 00

 "EX"

PidLidEmail1EmailAddress

PtypString 

 2F   00 6F 00 3D 00 46 00
 69   00 72 00 73 00 74 00
 20   00 4F 00 72 00 67 00
 61   00 6E 00 69 00 7A 00
 61   00 74 00 69 00 6F 00
 6E   00 2F 00 6F 00 75 00
 3D   00 45 00 78 00 63 00
 68   00 61 00 6E 00 67 00
 65   00 20 00 41 00 64 00
 6D   00 69 00 6E 00 69 00
 73   00 74 00 72 00 61 00
 74   00 69 00 76 00 65 00
 20   00 47 00 72 00 6F 00
 75   00 70 00 20 00 28 00
 46   00 59 00 44 00 49 00
 42   00 4F 00 48 00 46 00
 32   00 33 00 53 00 50 00
 44   00 4C 00 54 00 29 00
 2F   00 63 00 6E 00 3D 00
 52   00 65 00 63 00 69 00
 70   00 69 00 65 00 6E 00
 74   00 73 00 2F 00 63 00
 6E   00 3D 00 73 00 6F 00 6D 00 65 00 6F 00 6E 00 65 00 00 00

 "/o=First   Organization/ou=Exchange Administrative Group   (FYDIBOHF23SPDLT)/cn=Recipients/cn=someone"

PidLidEmail1OriginalDisplayName

PtypString 

 73   00 6F 00 6D 00 65 00 6F 00 6E 00 65 00 40 00 65 00 78 00 61 00 6D 00 70 00 6C   00 65 00 2E 00 63 00 6F 00 6D 00 00 00

 "someone@example.com"

PidLidEmail1OriginalEntryId

PtypBinary 

 7D   00 
 00   00 DC A7 40 C8 C0 42
 10   1A B4 B9 08 00 2B 2F
 E1   82 01 00 00 00 00 00
 00   00 2F 6F 3D 46 69 72
 73   74 20 4F 72 67 61 6E
 69   7A 61 74 69 6F 6E 2F
 6F   75 3D 45 78 63 68 61
 6E   67 65 20 41 64 6D 69
 6E   69 73 74 72 61 74 69
 76   65 20 47 72 6F 75 70
 20   28 46 59 44 49 42 4F
 48   46 32 33 53 50 44 4C
 54   29 2F 63 6E 3D 52 65
 63   69 70 69 65 6E 74 73
 2F   63 6E 3D 73 6F 6D 65 6F 6E 65 00

 Size:   125 bytes
 ....@..B
 ......+/
 ........
 ../o=Fir
 st   Organ
 ization/
 ou=Excha
 nge   Admi
 nistrati
 ve   Group
  (FYDIBO
 HF23SPDL
 T)/cn=Re
 cipients
 /cn=someo
 ne.

PidTagRtfCompressed ([MS-OXCMSG] section 2.2.1.58.4)

PtypBinary 

 E6   14
 E2   14 00 00 93 52 00 00
 4C   5A 46 75 62 F8 7E BB
 07   00 06 01 01 0B 60 6E
 67   31 30 32 66 35 00 64
 00   72 63 70 0D D0 0E 00
 32   05 0C 60 63 0D 44 66
 33   31 35 30 42 37 00 F5
 73   74 73 68 05 70 62 74
 …   (remainder of property excluded for brevity)

 Size:   5350 bytes
 .....R..
 LZFub.~.
 ......`n
 g102f5.d
 .rcp....
 2..`c.Df
 3150B7..
 stsh.pbt

PidTagMessageClass (section 2.2.1.11.2)

PtypString 

 49   00 50 00 4D 00 2E 00
 43   00 6F 00 6E 00 74 00
 61   00 63 00 74 00 00 00

 "IPM.Contact"

PidTagIconIndex ([MS-OXOMSG] section 2.2.1.10)

PtypInteger32 

 00   20 00 00

 512

PidTagSubjectPrefix ([MS-OXOMSG] section 2.2.1.60)

PtypString 

 00

 ""

PidTagSubject ([MS-OXPROPS] section 2.1034)

PtypString 

 4A   00 61 00 79 00 20 00 48 00 61 00 6D 00 6C 00 69 00 6E 00 00 00

 "Jay   Hamlin"

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.