Friday, June 22, 2007

COM Interface Reference

COM Interface Reference

COM Functions by Group:

Load a set of IDs of contacts

These functions will access listed contacts in Open Contacts windows, and load a set of IDs of the contacts into the Contacts Buffer and return the count.

HRESULT _stdcall GetSelectedPeopleCount([out, retval] int * v );

Reset the Contacts Buffer with selected contacts in the People List window and return the count of selected contacts. That is, the Contacts Buffer will have IDs of selected contacts.

Parameters:

None.

Return Values:

v -- Output the count of selected contacts.

HRESULT _stdcall GetPeopleCount([out, retval] int * x );

Reset the Contacts Buffer with all personal contacts, and return the count.

Parameters:

None.

Return Values:

x -- Output the count of all personal contacts.

HRESULT _stdcall GetListedPeopleCount([out, retval] int * v );

Reset Contacts Buffer with all listed contacts in the People List window.

Parameters:

None.

Return Values:

v -- Output the the count of listed contacts.

HRESULT _stdcall GetCompaniesCount([out, retval] int * v );

Reset the Contacts Buffer with all organizational contacts and return the count.

Parameters:

None.

Return Values:

v -- Output the count of selected contacts.

HRESULT _stdcall GetSelectedCompaniesCount([out, retval] int * v );

Reset the Contacts Buffer with selected contacts in the Companies List window and return the count of selected contacts.

Parameters:

None.

Return Values:

v -- Output the count of selected contacts.

HRESULT _stdcall GetListedCompaniesCount([out, retval] int * v );

Reset the Contacts Buffer with listed contacts in the Companies List window and return the count of listed contacts.

Parameters:

None.

Return Values:

v -- Output the count of listed contacts.

Search contacts

These functions may search contacts with a set of criteria, and reset the Contacts Buffer with the IDs of returned results.

HRESULT _stdcall FindName([in] BSTR n, [out, retval] VARIANT_BOOL * ID );

Search a contact by the full name, and reset the Contacts Buffer with an ID of the contact. The operation will search companies if the call is within a BeginCompanies/EndCompanies block, otherwise, search people.

Parameters:

n -- Full value of full name of the contact.

Return Values:

ID -- Return true if successful.

See Also:

BeginCompanies, EndCompanies

HRESULT _stdcall FindContactsByField([in] BSTR FieldName, [in] BSTR FieldValue, [out, retval] int * Count );

Search contacts with a pair of field name and field value, and reset the Contacts Buffer. The field name may be in the form of "SectionName\FieldName".

Parameters:

FieldName -- Dynamic field name of any section or a particular section. To search by a field name of a particular section, the field name is in the form of "SectionName\FieldName". For example, to search by the Phone fields of the Personal section, the FieldName is "Personal\Phone". The FieldName is case sensitive.

FieldValue -- Partial field value of a field, case-insensitive. For example, search by phone number "9987" may be matched with "99878903", "2399-8732" or "32339987".

Return Values:

Count -- The count of search results.

Note:

The ID of a contact might appear in the results more than once, if multiple fields of the contact match the search criteria. Because of the syntax of defining the section name, if you have field names or section names containing character "\", the search result might be confusing. Anyway, having a "\" in a field name is not recommended.

HRESULT _stdcall FindContactsByName([in] BSTR AName, [out, retval] int * Count );

Search by full name of contacts.

Parameters:

AName --Partial value of full name of contacts, case insensitive.

Return Values:

Count -- The count of the search results.

Note:

The results may be of people or companies.

HRESULT _stdcall FindContactsByPhone([in] BSTR Phone, [out, retval] int * Count );

Search contacts by a phone number. The operation will search all fields of action type "phone", therefore, fields like "Phone" and "Mobile" will be looked through.

Parameters:

Phone -- Partial phone number, case insensitive.

Return Values:

Count -- The count of the search results.

Note:

A contact might appear in the results more than once if multiple fields match the search criteria.

HRESULT _stdcall FindContactsByEmail([in] BSTR Email, [out, retval] int * Count );

Search contacts by Email address. The operation will search fields of action type "email", therefore, fields like "Email" and "Primary Email" will be taken care of.

Parameters:

Email -- Partial value of Email address.

Return Values:

Count -- The count of the search results.

HRESULT _stdcall FindContactsByDate([in] BSTR FieldName, [in] DATE DateBegin, [in] DATE DateEnd, [out, retval] int * Count );

Search contacts by a date field with value within a period.

Parameters:

FieldName -- Field name of a date field, such as "Birthday" or "Anniversary".

DateBegin -- Begin date of the period.

DateEnd -- End date of the period.

Return Values:

Count -- The count of the search results.

HRESULT _stdcall FindContactsByFieldType([in] BSTR FieldType, [in] BSTR FieldValue, [out, retval] int * Count );

Search contacts by fields of the same field type For example, search the "phone" type will eventually involve field "Phone", "Mobile" and "Fax" as both fields by default share the same field type "phone".

Parameters:

FieldType -- Field type of fields to search, such as "phone" and "bday". Case sensitive.

FieldValue -- Partial value of field values of contacts.

Return Values:

Count -- The count of the search results.

HRESULT _stdcall FindContactsByFieldAction([in] BSTR FieldAction, [in] BSTR FieldValue, [out, retval] int * Count );

Search contacts by fields of the same action type.

Parameters:

FieldAction -- Action type of fields to search, such as "phone" and "map". Case sensitive.

FieldValue -- Partial value of field values of contacts.

Return Values:

Count -- The count of the search results.

Manage Contacts Buffer and retrieve info

The functions manage the Contacts Buffer to reset or read some statuses.

HRESULT _stdcall GetIds([out, retval] BSTR * ids );

Return IDs of contacts in the Contacts Buffer.

Parameters:

None.

Return Values:

ids -- A list of IDs of contacts, as a comma separated string.

HRESULT _stdcall LocatePeople([in] int Idx );

Change current item of the Contacts Buffer by changing current item index.

Parameters:

Idx -- New index value. The index is 0 base.

Note:

This function works for both personal contacts and organizational contacts, despite of the function name.

HRESULT _stdcall GetContactID([in] int Idx, [out, retval] int * ID );

Get the contact ID of a contact in the buffer by the item index.

Parameters:

Idx -- Item index value. The index is 0 base.

Return Values:

ID -- Contact ID.

Access contacts in Contacts Buffer

Read and write upon current item of contacts in the Buffer.

HRESULT _stdcall GetName([out, retval] BSTR * v );

Get the full name of current item of contacts in the Buffer.

Parameters:

None.

Return Values:

v -- Full name of current item of contacts.

HRESULT _stdcall BeginCompanies( void );

Signal that the following functions will be for handling organizational contacts: CreateContact, FindName, BeginCategories, EndCategries. Other functions can work for both personal contacts and organizational contacts.

Parameters:

None.

Return Values:

None.

HRESULT _stdcall EndCompanies( void );

Mark the end of a section for organizational contacts.

Parameters:

None.

Return Values:

None.

HRESULT _stdcall GetField([in] BSTR Field, [out, retval] BSTR * v );

Get field value.

Parameters:

Field -- Field name of any section or a particular section. To access a field of a particular section, the search criteria is like "SectionName\FieldName".

Return Values:

v -- Field value. If not found, the value will be empty.

Note:

If there are multiple fields with the same field name, only the value of the first one found will be return.

HRESULT _stdcall SetField([in] BSTR FieldName, [in] BSTR FieldValue );

Set a field value of current item of contacts in the Buffer. The form of FieldName must be "SectionName\FieldName". If the field does not exist, the field will be created. If there are multiple fields with the same field name in the section, the first one found will be updated.

Parameters:

FieldName -- Field name of the field to set.

Return Values:

FieldValue -- Field value of the field to set.

HRESULT _stdcall GetNotes([out, retval] BSTR * v );

Get the value of the notes field of the primary section.

Parameters:

None.

Return Values:

v -- Field value of the notes field.

HRESULT _stdcall SetNotes([in] BSTR v );

Set the value of the notes field of the primary section.

Parameters:

v -- Value of the notes field to set.

Return Values:

None.

HRESULT _stdcall CreateContact([in] BSTR n, [out, retval] int * r );

Create a contact, and reset the Contacts buffer. If successful, the contact will become the current item in the Contacts Buffer.

Parameters:

n -- Full name of new contact.

Return Values:

r -- 0, if successful; 1, if contact with the same name exist; 2, fail.

Note:

By default, this function will create a person, and Open Contacts will analyze the full name into surname, given name and middle name. To create a company, contain the call inside in a BeginCompanies/EndCompanies block.

Visual control

Control some visual behaviors of Open Contacts

HRESULT _stdcall ShowOC( void );

Display Open Contacts.

HRESULT _stdcall RestoreOC( void );

Restore Open Contacts if minimized, and bring it to the front.

HRESULT _stdcall MinimizeOC( void );

Minimize Open Contacts.

HRESULT _stdcall RefreshOCNav( void );

Refresh the initial grids and the contact lists. This function is generally called after updating the database.

HRESULT _stdcall ClearPeopleEdit( void );

Clear the Edit Person window for new record.

HRESULT _stdcall ClearCompanyEdit( void );

Clear the Edit Company window for new record.

HRESULT _stdcall ShowContact([in] int Idx );

Show a contact of the Contacts Buffer, either in the Edit Person window or the Edit Company window.

Parameters:

Idx -- Item index of the contact.

Return Values:

None.

HRESULT _stdcall ViewContact([in] int ID );

Show a contact , either in the Edit Person window or the Edit Company window.

Parameters:

ID -- Contact ID of the contact.

Return Values:

None.

HRESULT _stdcall QuickViewContact([in] int ID );

Show a contact in the Quick View window.

Parameters:

ID -- Contact ID.

Return Values:

None.

HRESULT _stdcall SearchBirthdays([in] BSTR command, [out, retval] int * r );

Search contacts by birthday within a time frame. The birthday field is defined in the General tab of the Options. The call will bring up the Search Birthday window and list the results.

Parameters:

command -- Command that represents a time frame. Possible values are thismonth, nextmonth, thisweek, nextweek, today, and tomorrow.

Return Values:

r -- The count of the search results.

HRESULT _stdcall SearchBirthdaysBetween([in] int m1, [in] int d1, [in] int m2, [in] int d2, [out, retval] int * r );

Search contacts by birthday within a period of any year.

The birthday field is defined in the General tab of the Options. The call will bring up the Search Birthday window and list the results.

Parameters:

m1 -- Start month.

d1 -- Day of the start month.

m2 -- End month.

d2 -- Day of the end month.

Return Values:

r -- The count of the search results.

Search and get info directly

Search contacts and return results directly without UI change.

HRESULT _stdcall GetSelectedContactsEmails([out, retval] BSTR * v );

Get Email addresses of selected contacts in a contact list window such as the People List window and the Search window.

Parameters:

None.

Return Values:

A list of Email addresses separated by semicolon, presented in form "Contact Name".

Note:

If a contact has multiple Email addresses, the primary Email address of field type "aemail", or the first one found if no primary Email address is defined, will be returned.

HRESULT _stdcall GetListedContactsEmails([out, retval] BSTR * v );

Get Email addresses of listed contacts in a contact list window such as the People List window and the Search window.

Parameters:

None.

Return Values:

A list of Email addresses separated by semicolon, presented in form "Contact Name".

Statistic

Get some statistical data and settings of Open Contacts.

HRESULT _stdcall GetPredefinedFields([out, retval] BSTR * v );

Get predefined field names in a comma separated string.

HRESULT _stdcall GetExistingFields([out, retval] BSTR * v );

Get distinguish field names of all contacts.

HRESULT _stdcall GetPredefinedSectionNames([out, retval] BSTR * v );

Get names of predefined sections.

HRESULT _stdcall GetExistingSectionNames([out, retval] BSTR * v );

Get distinguish section names of all contacts.

Misc.

HRESULT _stdcall GetContactHTML([in] int ID, [out, retval] BSTR * html );

Return contact info in HTML format. The HTML content is generated though rendering the XML of the contacts with the default XSLT used in the Quick View window.

Parameters:

ID -- Contact ID.

Return Values:

html -- HTML content.

HRESULT _stdcall DoAction([in] BSTR Action, [in] BSTR Value );

Call a built-in function of action of Open Contacts. Each action type of dynamic fields is generally associated with a built-in function or program which can be triggered in Open Contacts by pressing F9. This function make Open Contacts become an action proxy.

Parameters:

Action -- Action type, case sensitive.

Value -- Value which the action will act on.

Return Values:

None.


HRESULT _stdcall BeginCategories( void );

Popup the Define Categories window, and all following new contacts will be assigned checked categories.

Note:

Within a BeginCompanies/EndCompanies, the Define Categories window brings up the category tree for companies.

HRESULT _stdcall Test( void );

A dummy function to test the existence of the COM server.

Purposing COM API functions

To better communicate with other programs and to make to programming job for client programs easier, some new API functions may will be published in the future.

  1. Return XML of a contact by contact ID. This will be handy the render the contact info into other formats.
  2. Return XML of contacts in the Contacts Buffer.
  3. Return vCard stream of contacts in the Contacts Buffer.
  4. Event: When a contact is added, return the contact ID.
  5. Event: When a contact is deleted, return the contact ID.
  6. Interface for address: is composed of Street, City, State and Geo etc, and section name as well.
  7. Return the address of a section of a contact.
  8. Return the addresses of a contact.
  9. Interface of settings: While Open Contacts stored almost all settings in the address book database, the interface provides a subset of the settings.

Posted by at
Labels: ,