Integrator C Series API

The phone book

The phone book commands lets you add, search and delete phone book entries for local and corporate phone books.

Definitions

Local Phone book

A phone book that is stored locally on the codec. Entries may be added/edited/deleted using API or by user using the remote control.

Corporate Phone book

A phone book that is retrieved from a common source, usually from TANDBERG Management Suite (TMS). Searchable via the API. No updates are possible. It is TMS that decides which phone book directories are available when searching in the corporate phone book.

Contact

An entity (person/room/video system) in the phone book.

ContactMethod

A method of connecting to a contact. A contact may have several contactMethods for e.g. video, video at home office, cellphone, land line etc. A contact method has a Number, a Protocol and a device description.

Folder

A collection of Contacts. A folder may also contain sub-folders. When searching using Corporate Phone book, multiple phone book directories will be represented as folders.

The Search Command

The search command lets you search in both local and corporate phone books. A search will give a ResultSet.

xCommand Phonebook Search
    PhonebookId: 
    PhonebookType: 
    SearchString: 
    SearchField: 
    Offset: <0..65534>
    FolderId: 
    Limit: <0..65534>

Arguments

• PhonebookId: <S: 0, 255>: The value of the ID tag for which phonebook server to use. See xConfiguration Phonebook Server. Not necessary to use.
• PhonebookType: <Corporate/Local>: Which phone book to search in. Either the local phone book or the corporate phonebook.
• SearchString: <S: 0, 255>: Search for entries containing specified string (not begins with). If no FolderId is specified, the search will yield search results from ALL folders/phonebook directories. This parameter is optional for TC 2.0 and higher.
• SearchField: <Name/Number>: Currently not in use
• FolderId: <S: 0, 255>: Search only in the specified folder. FolderId (string) is listed in the ResultSet of a search result containing folders.
• Offset: <0..65534>: Get records starting with this offset in a search. Default 0. Used together with Limit to support paging.
• Limit: <0..65534>: Limit the number of records in the result set to this number. E.g. Limit: 10 will only give a ResultSet of 10 entries (Contacts + Folders) although the total number of hits may be greater.

The format of a phone book search result

A phone book search result consists multiple lines prefixed with *r ResultSet:

*r ResultSet ResultInfo TotalRows: 33
*r ResultSet Contact 1 Name: "Peter Pan"
*r ResultSet Contact 1 ContactId: "localContactId-15"
*r ResultSet Contact 1 ImageUrl: ""
*r ResultSet Contact 1 ContactMethod 1 ContactMethodId: "120"
*r ResultSet Contact 1 ContactMethod 1 Number: "peter@neverland.com"
*r ResultSet Contact 1 ContactMethod 1 Protocol: H323
*r ResultSet Contact 1 ContactMethod 1 Device: Video
*r ResultSet Contact 1 ContactMethod 2 ContactMethodId: "120"
*r ResultSet Contact 1 ContactMethod 2 Number: "peter.pan@homeland.com"
*r ResultSet Contact 1 ContactMethod 2 Protocol: H323
*r ResultSet Contact 1 ContactMethod 2 Device: Video
*r ResultSet Contact 2 Name: "John Doe"
*r ResultSet Contact 2 ContactId: "localContactId-13"
*r ResultSet Contact 2 ContactMethod 1 ContactMethodId: "66"
*r ResultSet Contact 2 ContactMethod 1 Number: "john.Office@tandberg.com"
*r ResultSet Contact 2 ContactMethod 1 Protocol: H323
*r ResultSet Contact 2 ContactMethod 1 CallRate: 768
*r ResultSet Contact 2 ContactMethod 2 ContactMethodId: "67"
*r ResultSet Contact 2 ContactMethod 2 Number: "john.Home0@tandberg.com"
*r ResultSet Contact 2 ContactMethod 2 Protocol: H323
...

*r ResultSet Folder 1 Name: " Friends"
*r ResultSet Folder 1 FolderId: "localGroupId-38"
*r ResultSet Folder 2 Name: "Children"
*r ResultSet Folder 2 FolderId: "localGroupId-5"
...
** end

The structure of the ResultSet is exactly the same regardless of doing a local or a corporate search.

• The first line *r ResultSet ResultInfo TotalRows: 33 tells how many possible hits (folders+contacts) there are in total for the search you made (not to be mistaken as the returned number of contacts + folders in the resultSet).
• All Contacts start with Contact followed by a sequence number 1..n (unique only to that ResultSet)
• All Folders start with Folder followed by a sequence number 1..n (unique only to that ResultSet)

A search resultwith no matches

If you do a search that results in no hits you will get the following ResultSet:

*r ResultSet ResultInfo TotalRows: 0
** end

Using Offset and Limit parameteres

Using the *r ResultSet ResultInfo TotalRows: x information together with the Offset and Limit parameters we can create paging-logic.

Example

If you only want to display 8 entries per page on your GUI you would use Limit:8 to never get more that 8 entries in the resultset at a time.

Retrieve the first 8 entries:

xCommand Phonebook Search phonebookType:Corporate Limit:8 Offset:0

*r ResultSet ResultInfo TotalRows: 33
*r ResultSet Contact 1 Name: "Peter Pan"
*r ResultSet Contact 1 ContactId: "localContactId-15"
*r ResultSet Contact 1 ImageUrl: ""
*r ResultSet Contact 1 ContactMethod 1 ContactMethodId: "120"
*r ResultSet Contact 1 ContactMethod 1 Number: "peter@neverland.com"
*r ResultSet Contact 1 ContactMethod 1 Protocol: H323
*r ResultSet Contact 1 ContactMethod 1 Device: Video
...

Retrieve the next entries (one at a time):

xCommand Phonebook Search phonebookType:Corporate Limit:8 Offset:8
xCommand Phonebook Search phonebookType:Corporate Limit:8 Offset:16
xCommand Phonebook Search phonebookType:Corporate Limit:8 Offset:24
xCommand Phonebook Search phonebookType:Corporate Limit:8 Offset:8*x
...

Since we know that offset + limit (32+8) is now higher than totalrows (33) we know that there won't be any more results after this.