Oxmapi
Introduction
This document defines
OXMAPI32 API. It provides access to a Open-Xchange 6 Server by using
the Open-Xchange HTTP API. The OXMAPI32 API can be used for Windows
applications. The OXMAPI32 API architecture bases on the Microsoft
MAPI so the convention of constants and objects are similar.
This document describes the functionality of each object in the respective module, which are ordinated corresponding the object model. Each module provides code
examples how to use the respective object written in Delphi.
OXMAPI Object Model
<IMG SRC="oxmapi32_html_m7b3028d.png" NAME="Grafik1" ALIGN=LEFT WIDTH=642 HEIGHT=238 BORDER=0>
Constants
This topic provides a list of all constant in the object model. OlDefaultFolders relate to the default folder subordinated to the private folder of the current user.
Name |
Value |
OlAppointmentItem |
1 |
olContactItem |
2 |
OlDistributionListItem |
7 |
olTaskItem |
3 |
Table 1. OlItemType
Name |
Value |
olFolderCalendar |
9 |
olFolderContacts |
10 |
olFolderlTasks |
13 |
Table 2. OlDefaultFolders
Name |
ID |
private |
1 |
public |
2 |
shared |
3 |
Table 3. top level folder IDs
App Object
Represents the root for any data source object. The App Object has several purposes:
As the root object, it allows access to other objects in the oxmapi hierarchy.
It allows access to a new item created by using CreateItem.
It provides methods accessing certain special default folders directly.
It provides the Entry Point for establishing the connection
Name |
Type |
Description |
Application |
IApp |
Readonly: Reference to the App Object itself. |
Name |
Variant |
Readonly: Name of the Application. |
Session |
ISession |
Readonly: Reference to the current Session Object. |
Version |
Variant |
Readonly: Number of the current Version |
Table 4. App Properties
Name |
Result |
Parameters |
Description |
CreateItem |
IItem |
Item: OlDefaultItems |
Creates a new item and returns it. The CreateItem method can only create items listet in Table 1 |
CreateRecipient |
IRecipient |
Value: Variant |
Creates and returns a Recipient object. |
GetDefaultFolder |
IMAPIFolder |
Name: OlDefaultFolders |
Returns a MAPIFolder object that represents the default folder of the requested type for the current profile. Default folders are described in Table 2 |
GetFolderFromID |
IMAPIFolder |
ID: Variant |
Returns a MAPIFolder object identified by the specified entry ID (if valid). |
Quit |
The associated session is closed completely; the user is logged out of the messaging system and any changes to items not already saved are discarded. |
Table 5. App Methods
Using the App Object
Use the CoClass.Create method to instantiate a new Application.
Delphi code example: |
var Application: App; begin Application := CoApp.Create; |
Examples showing how to use the functions of the App Object are described in the corresponding module. An example for a folder request is presented in the module of the MAPIFolder object. An example how to create items is presented in the module of the Item Interface .
Session Object
Represents a connection to the OX-Server. The object itself provides methods for logging in and out. The Logon Method requires a valid IP-Address to the server.
Name |
Type |
Description |
Parent |
IApp |
Readonly: Reference to the current App Object. |
Session |
ISession |
Readonly: Reference to the Session Object itself. |
Connected |
WordBool |
Readonly: Flag which indicates whether Session is connected to the server or not. |
Table 6. Session Properties
Name |
Result |
Parameters |
Description |
SetIP |
HRESULT |
Value: Variant |
|
Logon |
HRESULT |
Username, Password: Variant |
Logs the user on to MAPI, obtaining a MAPI session. |
Logoff |
HRESULT |
Logs the user off from the current MAPI session. |
Table 7. Session Methods
Using the Session Object
To establish a connection to the server, use the following example:
Delphi code example: Connection |
var Application: App; begin Application.Session.SetIP('192.168.0.1'); Application.Session.Logon; |
MAPIFolder Object
Represents a folder. A MAPIFolder object can contain other MAPIFolder objects, as well as items. Therefore the MAPIFolder Object contains the Folders Object and the Items Object to obtain subordinated elements. You can navigate nested folders by using a combination of Folders.item(index), which returns the subfolder with the position of the index.
The MAPIFolder Object is typed; for example, the Calendar folder will only contain AppointmentItem objects and the Contacts folder will only contain ContactItem and DistListItem objects.
Name |
Type |
Description |
Application |
IApp |
Readonly: Reference to the current App Object. |
EntryID |
Variant |
Readonly: Folder ID of corresponding folder on the server. |
Parent |
IMAPIFolder |
Readonly: Reference to the Parentfolder. If the current folder is a root folder (private folder, public folder, shared folder or infostore) this property returns null. |
Session |
ISession |
Readonly: Reference to the current Session Object. |
Folders |
IFolders |
Readonly: Folders Object representing all subfolders contained in this folder. |
Items |
IItems |
Readonly: Items Object representing all items contained in this folder. |
Name |
Variant |
Read/Write: Name of the folder. |
Category |
Variant |
Readonly: Category of the folder. |
Table 8. MAPIFolder Properties
Name |
Result |
Parameters |
Description |
Delete |
HRESULT |
Deletes the folder | |
MoveTo |
HRESULT |
DestinationFolder: MAPIFolder |
Moves the folder to the specified destination folder |
Table 9. MAPIFolder Methods
Using the MAPIFolder Object
This example uses the GetDefaultFolder method to obtain the default Calendar folder for a user who is currently logged in. Use OlDefaultFolders described in Table 2 to obtain the default folder.
Delphi code example: GetDefaultFolder |
var Application: App; Folder: MAPIFolder; begin Folder := App.GetDefaultFolder(olFolderCalendar); end; |
The default folders constants provides access to the private default folders. To obtain a top level folder, use the GetFolderFromID method. The following example shows how to obtain the private folder.
Delphi code example: GetFolderFromID |
var Application: App; Folder: MAPIFolder; begin Folder := App.GetFolderFromID('1'); end; |
To add a new folder, use the add method of the Folders property. An example how to add a folder is presented in the Folders Object module. To add a new item, use the add method of the Items property. An example how to add a item is presented in the Items Object module.
Folders Object
Represents all folders in a MAPIFolder object. The Folders Object provides a collection of methods to obtain subordinated folders.
Name |
Type |
Description |
Application |
IApp |
Readonly: Reference to the current App Object. |
Parent |
IMAPIFolder |
Readonly: Reference to the MAPIFolder Object. |
Session |
ISession |
Readonly: Reference to the current Session Object. |
Count |
Long |
Readonly:Number of subfolders contained in the Parent MAPIFolder |
Table 10. Folders Properties
Name |
Result |
Parameters |
Description |
Add |
MAPIFolder |
Name: Variant, Type_: OlDefaultFolders |
Creates a new folder in the Parent MAPIFolder. |
Find |
MAPIFolder |
Filter: Variant |
Locate and returns a direct subfolder |
GetFirst |
MAPIFolder |
Returns the first subfolder | |
GetLast |
MAPIFolder |
Returns the last subfolder | |
GetNext |
MAPIFolder |
Returns the next subfolder. It returns null if no next subfolder exists, if already positioned at the last folder. | |
GetPrevious |
MAPIFolder |
Returns the previous subfolder. It returns null if no previous subfolder exists, if already positioned at the first folder. | |
Item |
MAPIFolder |
Index: long |
Returns a subfolder positioned at the index number. |
Remove |
HRESULT |
Index: long |
Deletes a subfolder positioned at the index number |
Table 11. Folders Methods
Using the Folders Object
This example uses the item method to visit subordinated folders and returns the folder “old contacts”.
Delphi code example: visit subfolders |
Var i: integer; Application: App; Contactfolder, Folder: MAPIFolder; begin Contactfolder := App.GetDefaultFolder(olFolderCalendar); for i := 0 to Contactfolder.Count-1 begin Folder := Contactfolder.folders.item(i); if (Folder.Name = 'old contacts') then begin Result := Folder; end else begin Result := nil; end; end; end; |
To add a new folder, use the add method. The Add method has an optional argument that can be used to specify the type of items that can be stored in that folder. By default, folders created inside another folder inherit the type of the parent folder.
Delphi code example: add a new folder |
var Application: App; newfolder, Contactfolder: MAPIFolder; begin Contactfolder := App.GetDefaultFolder(olFolderCalendar); newfolder := Contactfolder.Folders.add('new contactfolder',olFolderContacts);end; |
Items Object
Represents all Items in a MAPIFolder object. The Items Object provides a collection of methods to obtain subordinated folders.
Name |
Type |
Description |
Application |
IApp |
Readonly: Reference to the current App Object. |
Parent |
IMAPIFolder |
Readonly: Reference to the MAPIFolder Object. |
Session |
ISession |
Readonly: Reference to the current Session Object. |
Count |
Long |
Readonly:Number of Items contained in the Parent MAPIFolder |
Table 12. Items Properties
Name |
Result |
Parameters |
Description |
Add |
IItem |
Name: Variant, Type_: OlDefaultItems |
Creates a temporary Item in the Parent MAPIFolder. To create a persistent item, invoke the save method of the item. |
Find |
IItem |
Filter: Variant |
Locate and returns a Item matching the Filter. |
GetFirst |
IItem |
Returns the first Item. | |
GetLast |
IItem |
Returns the last Item. | |
GetNext |
IItem |
Returns the next Item. It returns null if no next Item exists, if already positioned at the last Item. | |
GetPrevious |
IItem |
Returns the previous Item. It returns null if no previous Item exists, if already positioned at the first Item. | |
Item |
IItem |
Index: long |
Returns a Item positioned at the index number. |
Remove |
HRESULT |
Index: long |
Deletes a Item positioned at the index number. |
Table 13. Items Methods
Using the Items Object
This example uses the item method to obtain items contained in the parent folder.
Delphi code example: obtaining folder items |
Var i: integer; Application: App; Contactfolder: MAPIFolder; Currentitem: Item; begin Contactfolder := App.GetDefaultFolder(olFolderCalendar); for i := 0 to Contactfolder.Count-1 begin Currentitem := Contactfolder.items.item(i); if (Currentitem.Subject = 'John Smith') then begin Result := Current; end else begin Result := nil; end; end; end; |
To
add a new item, use the add method. The Add method has an optional argument that can be used to specify the type of the item. By default, items created inside the parent folder inherit the type by means of the parent folder. In the case a contact folder adds a new item, the result is an Item interface referring to a ContactItem
Object.
The
Add method creates a temporary and specific item. To make it
persistent, it needs to be saved by invoking the Save method.
Delphi code example: add a new item |
var Application: App; Contactfolder: MAPIFolder; Newitem: Item; begin Contactfolder := Application.GetDefaultFolder(olFolderContacts); Newitem := Contactfolder.Items.add(olContactItem); Newitem.Subject := 'John Smith'; Newitem.Save; end; |
Item Interface
The Item interface is a common Interface to handle basic functions of a specific item object and to abstract the specific items.
The Item interface is the root for all specific item interfaces; for example, a ContactItem interface inherits the properties and methods of the Item interface.
To
identify an item, use the Message Class property. Message Class
Values are described in Table 14.
-
MessageClass
IPM.Appointment
IPM.Contact
IPM.DistList
IPM.Task
Table 14. MessageClasses
Name |
Type |
Description |
Application |
IApp |
Readonly: Reference to the current App Object. |
EntryID |
Variant |
Readonly: ID of corresponding item on the server. |
Parent |
IMAPIFolder |
Readonly: Reference to the Parentfolder. If the current folder is a root folder (private folder, public folder, shared folder or infostore) this property returns null. |
Session |
ISession |
Readonly: Reference to the current Session Object. |
CreationTime |
Date |
|
Body |
Variant |
Readonly: Items Object representing all items contained in this folder. |
Subject |
Variant |
Read/Write: Name of the folder. |
Saved |
Wordbool |
Readonly: indicates whether the save method has been successfull.or not |
MessasgeClass |
Variant |
Table 15. Item Properties
Name |
Result |
Parameters |
Description |
Delete |
HRESULT |
Deletes the item | |
Move |
HRESULT |
DestinationFolder: MAPIFolder |
Moves the item to the specified destination folder |
Save |
HRESULT |
Stores a new item on the server or updates the existing one. If required properties are not set, the Save method will fail. |
Table 16. Item Methods
Using the Item Interface
The following example shows how to create a new Appointment in the default calendar folder. To use the new item as Appointment, the Item interface has to be casted to an AppointmentItem.
Remark: Like the Add method in the Items Object, CreateItem also creates a temporary item. To make it persistent, the Save method has to be invoked.
Delphi code example: CreateItem |
var Application: App; Newitem: Item; NewAppointment: AppointmentItem; begin Newitem := Application.CreateIem(olAppointmentItem); NewAppointment := Newitem as AppointmentItem; end; |
AppointmentItem Object
Represents an appointment in the Calendar folder. An AppointmentItem posses properties described in Table 15 and Table 17, methods described in Table 16. Valid Values in Subject, StartDate and EndDate properties are required for saving.
Name |
Type |
Description |
EndDate |
Date |
Read/Write: |
StartDate |
Date |
Read/Write: |
Location |
Variant |
Read/Write: |
Table 17. AppointmentItem Properties
Using the AppointmentItem Object
The following example shows how to create a new Appointment.
Delphi code example: Create a new Appointment |
var Application: App; NewAppointment: AppointmentItem; begin NewAppointment := Application.CreateIem(olAppointmentItem) as AppointmentItem; NewAppointment.Subject := 'Meeting'; NewAppointment.StartDate := StrToDateTime('01.01.2007 15:00); NewAppointment.EndDate := StrToDateTime('01.01.2007 15:00); NewAppointment.Save; end; |
ContactItem Object
Represents a contact in a contacts folder. A contact can represent any person with whom you have any personal or professional contact. A ContactItem posses properties described in Table 15 and Table 18, methods described in Table 16. A valid Value in LastName property is required for saving.
Name |
Type |
Description |
EmailAddress1 |
Variant |
Read/Write:.first email |
BusinessTelephoneNumber |
Variant |
Read/Write: Telephonenumber |
FirstName |
Variant |
Read/Write: First name |
LastName |
Variant |
Read/Write:.Last name |
Company |
Variant |
Read/Writ: Company |
HomeAddressCity |
Variant |
Read/Write: City of Home Address |
Table 18. ContactItem Properties
Using the ContactItem Object
The following example shows how to create a new Contact.
Delphi code example: Create a new Contact |
var Application: App; Newcontact: ContactItem; begin Newcontact := Application.CreateIem(olContactItem) as ContactItem; Newcontact.FirstName := 'John'; Newcontact.LastName := 'Smith'; Newcontact.EmailAddress1 := 'john.smith@acme.com' Newcontact.Save; end; |
DistListItem Object
Represents a distribution list in a contacts folder. A distribution list can contain multiple recipients and is used to send messages to everyone in the list. A DistListItem posses properties described in Table 15 and Table 19, methods described in Table 16 and Table 20. A valid Value in the Subject property is required.
Name |
Type |
Description |
MembersCount |
long |
ReadOnly:.Number of Members in the Distributionlist |
Members |
Variant |
Read/Write:Array of string containing each member of the Distributionlist. The string format is ***Name***/n/r***Mailaddress*** |
Table 19. DistListItem Properties
Name |
Result |
Parameters |
Description |
AddMember |
HRESULT |
Recipient: IRecipient |
Adds a new Member to the Disptributionlist. |
GetMember |
IRecipient |
Index: long |
Returns a Recipient positioned at the index. |
RemoveMember |
HRESULT |
Index: long |
Deletes Member from the Distributionlist |
Table 20. DistListItem Methods
Using theDistListItem Object
The following example shows how to create a new Distributionlist. Use the CreateRecipient method to create a Recipient and add it to the Distributiolist.
Delphi code example: Create a new Distributionlist |
var Application: App; Newdistlist: DistlistItem; Newrecipient: Recipient; begin Newdistlist := Application.CreateItem(olContactItem) as DistListItem; Newrecipient := Application.CreateRecipient('John Smith'); Newdistlist.Subject := 'Businesspartners'; Newrecipient.Address := <A HREF="mailto:'john.smith@acme.com">'john.smith@acme.com</A>'; Newdistlist.AddMember(Newrecipient); Newdistlist.Save; end; |
TaskItem Object
Represents a task (an assigned, delegated, or self-imposed task to be performed within a specified time frame) in a Tasks folder. A TaskItem posses properties described in Table 15 and Table 21, methods described in Table 16.
Name |
Type |
Description |
EndDate |
Date |
Read/Write: End date |
StartDate |
Date |
Read/Write: Start date |
Importance |
long |
Read/Write: Priority of the Item. 0 = low, 1 = middle, 2 = high |
Table 21. TaskItem Properties
Using the TaskItem Object
The following example shows how to create a new Task.
Delphi code example: Create a new Task |
var Application: App; Newtask: TaskItem; begin Newcontact := Application.CreateIem(olContactItem) as ContactItem; Newcontact.FirstName := 'John'; Newcontact.LastName := 'Smith'; Newcontact.EmailAddress1 := 'John.Smith@acme.com' Newcontact.Save; end; |
Recipient Object
Represents a user or resource, generally a mail message addressee.
Name |
Type |
Description |
EntryID |
Variant |
ReadOnly: |
Address |
Variant |
Read/Write: |
Name |
Variant |
Read/Write: |
Session |
ISession |
Readonly: Reference to the current Session Object. |
MailField |
Variant |
Read/Write: |
FirstName |
Variant |
ReadOnly: |
LastName |
Variant |
ReadOnly: |
Table 22. Recipient Properties
Using the Recipient Object
An example how to use the the Recipient Object is described in the DistListItem Object module.
[[Category: OX Hyperion related]}