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]}