Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

78    Telephony Phone Book

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter describes the phone book service set of the telephony API.

For more information about the telephony manager basic services and the different service sets, see Chapter 73, "Telephony Basic Services."

This chapter describes:

For more information about using the telephony manager, see Chapter 10, "Telephony Manager," in Palm OS Programmer's Companion, vol. II, Communications.

Telephony Phone Book Data Structures ^TOP^

This chapter describes the data structures used with the phone book service set of the telephony API.

TelPhbEntryType Struct ^TOP^

Purpose

The TelPhbEntryType structure describes a single entry in a phone book.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelPhbEntryType {
   UInt16 phoneIndex;
   Char *fullName;
   UInt8 fullNameSize;
   Char *dialNumber;
   UInt8 dialNumberSize;
} TelPhbEntryType

Fields

→ phoneIndex
The index of the entry in the phone's phone book. This index is always zero-based.
The telephony manager is responsible for converting this index into the physical index in the phone, if required.
← fullName
A buffer into which the retrieved full name of the entry is stored.
This string is stored using the local character set of the Palm™ handheld device. The telephony manager is responsible for converting the character set, if required.
Note that if this buffer is too small to contain the entire retrieved string, the string is truncated and the function using this structure generates a telErrBufferSize error.
fullNameSize
The size of the fullName string.
When the structure is used as an input parameter, this is the allocated size, in bytes, of the fullName buffer.
Upon return, this is the actual size of the string, including the null terminator character. If the fullName buffer is too small to contain all of the retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.
← dialNumber
A buffer into which the retrieved telephone number of the entry is stored.
Note that if this buffer is too small to contain the entire retrieved string, the string is truncated, and the function using this structure generates a telErrBufferSize error.
dialNumberSize
The size of the dialNumber string.
When the structure is used as an input parameter, this is the allocated size, in bytes, of the dialNumber buffer.
Upon return, this is the actual size of the string, including the null terminator character. If the dialNumber buffer is too small to contain all of the retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.

TelPhbGetAvailablePhonebooksType Struct ^TOP^

Purpose

The TelPhbGetAvailablePhonebooks() functions uses the TelPhbGetAvailablePhonebooksType structure to return a list of the phone books available on the phone.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelPhbGetAvailablePhonebooksType {
   UInt16 count;
   UInt8 *phonebooksP;
} TelPhbGetAvailablePhonebooksType

Fields

↔ count
The number of entries in the array referenced by phonebooksP.
When the structure is used as an input parameter, this is the allocated size, in bytes, of the phonebooksP buffer. Upon return, this is the actual size of the retrieved data.
Upon return, this is the actual number of phone book IDs that could be retrieved. If the phonebooksP buffer is too small to contain all of the IDs, this field is assigned the actual count, and the function using this structure generates a telErrBufferSize error.
← phonebooksP
An array of retrieved phone book IDs. Each ID is one of the Phone Book Type Constants.

TelPhbGetEntriesType Struct ^TOP^

Purpose

The TelPhbGetEntries() function uses the TelPhbGetEntriesType structure to return a list of phone entries.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelPhbGetEntriesType {
   UInt16 first;
   UInt16 count;
   TelPhbEntryType *entriesP;
} TelPhbGetEntriesType

Fields

→ first
The index of the first entry in the array referenced by entriesP.
count
When the structure is used as an input parameter, this is number of entries that you want retrieved.
Upon return, this is the actual number of entries that were retrieved.
← entriesP
An array of pointers to retrieved TelPhbEntryType structures.

TelPhbGetEntryCountType Struct ^TOP^

Purpose

The TelPhbGetEntryCount() function uses the TelPhbGetEntryCountType structure to return information about the entries in the currently selected phone book.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelPhbGetEntryCountType {
   UInt16 slots;
   UInt16 count;
} TelPhbGetEntryCountType

Fields

← slots
The total number of entry slots available in the phone book.
count
The number of filled slots in the phone book.

TelPhbGetEntryMaxSizesType Struct ^TOP^

Purpose

The TelPhbGetEntryMaxSizes() function uses the TelPhbGetEntryMaxSizesType structure to return size information about the entries in the currently selected phone book.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelPhbGetEntryMaxSizesType {
   UInt8 fullNameMaxSize;
   UInt8 dialNumberMaxSize;
} TelPhbGetEntryMaxSizesType

Fields

← fullNameMaxSize
The largest size of any fullName field in the phone book.
← dialNumberMaxSize
The largest size of any dialNumber field in the phone book.

Telephony Phone Book Constants ^TOP^

This section describes the constants used with the phone book service set of the telephony API.

Phone Book Type Constants ^TOP^

Purpose

The phone book type constants specify the type of phone book that is currently selected.

Declared In

TelephonyMgr.h

Constants

#define kTelPhbFixedPhonebook 0
The phone book stored on the phone.
#define kTelPhbSimPhonebook 1
The phone book stored on the SIM card.
#define kTelPhbPhonePhonebook 2
The phone book stored on the phone.
#define kTelPhbLastDialedPhonebook 3
The phone book from which a telephone number was most recently dialed.
#define kTelPhbSimAndPhonePhonebook 4
The combined phone and SIM card phone books.
#define kTelPhbAdaptorPhonebook 5
The phone book stored on the telephone adaptor.
#define kTelPhbFirstOemPhonebook 6
The ID of the first OEM phone book.
You can specify additional OEM phone books by incrementing this value; for example, the second OEM phone book is specified as kTelPhbFirstOemPhonebook+1.

Telephony Phone Book Functions ^TOP^

This section describes the functions used with the phone book service set of the telephony API.

TelPhbAddEntry Function ^TOP^

Purpose

Add or replace an entry in the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbAddEntry(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbEntryType *iEntryP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iEntryP
A pointer to a TelPhbEntryType structure that contains the new entry information.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the TelPhbEntryType structure passed to this function in the iEntryP parameter.
functionId
kTelPhbAddEntryMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by iEntryP remains in memory until the asynchronous call completes.

Comments

The phoneIndex field of the TelPhbEntryType structure referenced by iEntryP specifies the index at which to write the entry.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbDeleteEntry(), TelPhbSelectPhonebook()

TelPhbDeleteEntry Function ^TOP^

Purpose

Deletes an entry from the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbDeleteEntry(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 iEntryIndex,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iEntryIndex
The zero-based, logical index of the entry that you want deleted. The Telephony Manager computes the physical index.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the unsigned integer value passed to this function in the iEntryIndex parameter.
functionId
kTelPhbDeleteEntryMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by iEntryP remains in memory until the asynchronous call completes.

Comments

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbAddEntry(), TelPhbSelectPhonebook()

TelPhbGetAvailablePhonebooks Function ^TOP^

Purpose

Retrieve the list of all phone books available on the phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetAvailablePhonebooks(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbGetAvailablePhonebooksType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a TelPhbGetAvailablePhonebooksType structure that lists the available phone books.
On input, the count field of this structure specifies the allocated size of the phonebookP buffer. Upon return, the count field specifies the actual number of entries retrieved, even if they were truncated to fit into the buffer.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the TelPhbGetAvailablePhonebooksType structure passed to this function in the iEntryP parameter.
functionId
kTelPhbGetAvailablePhonebooksMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Comments

The phone book IDs are stored into the phonebookP field of the TelPhbGetAvailablePhonebooksType structure referenced by ioParamP. If the phonebookP buffer is too small to contain all of the IDs, the information is truncated and this function returns the telErrBufferSize error. The count field of the structure is always updated to contain the actual number of entries that were retrieved.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbSelectPhonebook()

TelPhbGetEntries Function ^TOP^

Purpose

Retrieve a range of entries from the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetEntries(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbGetEntriesType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a TelPhbGetEntriesType structure that is updated with the phone book entry information. The first entry retrieved is specified in the first field of this structure, which is zero-based; the number of entries retrieved is specified by the count field. Thus, the last entry retrieved is specified by:
ioParamP->first +
    ioParamP->count-1
Upon return, the count field of the structure is the number of entries that were actually retrieved.
The entriesP field of this structure is a buffer that you allocate to contain the required number of pointers. Each pointer references a TelPhbEntryType structure that you must also preallocate.
On input, the fullNameSize and dialNumberSize fields of this structure specify the allocated sizes of the fullName and dialNumber buffers. Upon return, the fullNameSize and dialNumberSize fields specify the actual sizes of the buffers, even if a string was truncated to fit into the buffer.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure
transId
The transaction ID of the operation.
paramP
Points to the TelPhbGetEntriesType structure passed to this function in the ioEntriesP parameter.
functionId
kTelPhbGetEntriesMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP and any structures that it references remain in memory until the asynchronous call completes.

Comments

The phone book information is stored into the TelPhbEntryType structures that you preallocate and refer to in the entriesP field of the TelPhbGetEntriesType referenced by the ioParamP parameter.

If any buffer in any of the TelPhbEntryType structures is too small, the string intended for that buffer is truncated, and this function returns the telErrBufferSize error. In any case, the fullNameSize and dialNumberSize fields of each TelPhbEntryType structure contain the actual size of their respective strings.

If any entries in the specified range are empty, the entry is not retrieved, and the count value in the structure is updated.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbGetEntry(), TelPhbSelectPhonebook()

TelPhbGetEntry Function ^TOP^

Purpose

Retrieve one entry from the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetEntry(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbEntryType *ioEntryP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioEntryP
A pointer to a TelPhbEntryType structure that is updated with the phone book entry information.
On input, the fullNameSize and dialNumberSize fields of this structure specify the allocated sizes of the fullName and dialNumber buffers. Upon return, the fullNameSize and dialNumberSize fields specify the actual sizes of the buffers, even if a string was truncated to fit into the buffer.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the TelPhbEntryType structure passed to this function in the ioEntryP parameter.
functionId
kTelPhbGetEntryMessage

Comments

The phone book information is stored into the TelPhbEntryType that you preallocate. If either buffer in the structure is too small, the string intended for that buffer is truncated, and this function returns the telErrBufferSize error. In any case, the fullNameSize and dialNumberSize fields of the structure contain the actual size of their respective strings.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbGetEntries(), TelPhbSelectPhonebook()

TelPhbGetEntryCount Function ^TOP^

Purpose

Retrieve the total number of entries, and the number of filled entries in the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetEntryCount(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbGetEntryCountType *oParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oParamP
A pointer to a TelPhbGetEntryCountType structure that is updated with information about the number of entries in the phone book.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the TelPhbGetEntryCountType structure passed to this function in the oParamP parameter.
functionId
kTelPhbGetEntryCountMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by oParamP remains in memory until the asynchronous call completes.

Comments

The total number of slots and the number of filled slots in the currently selected phone book are stored in the TelPhbGetEntryCountType structure referenced by oParamP.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbSelectPhonebook()

TelPhbGetEntryMaxSizes Function ^TOP^

Purpose

Retrieves the maximum buffer sizes of any entries in the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetEntryMaxSizes(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelPhbGetEntryMaxSizesType *oParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oParamP
A pointer to a TelPhbGetEntryCountType structure that is updated with information about the maximum buffer sizes of entries in the phone book.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the TelPhbGetEntryCountType structure passed to this function in the oParamP parameter.
functionId
kTelPhbGetEntryMaxSizesMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by oParamP remains in memory until the asynchronous call completes.

Comments

The maximum size of any full name entry and the maximum size of any telephone number entry in the currently selected phone book are stored in the TelPhbGetEntryCountType structure referenced by oParamP.

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbGetEntries(), TelPhbGetEntry()

TelPhbGetSelectedPhonebook Function ^TOP^

Purpose

Retrieve the ID of the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbGetSelectedPhonebook(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt8 *oPhbIdP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oPhbIdP
A pointer to an unsigned byte value. Upon return, this is filled in with the identifier of the currently selected phone book. The identifier is one of the Phone Book Type Constants.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the unsigned integer value passed to this function in the oPhIdP parameter.
functionId
kTelPhbGetSelectedPhonebookMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by oPhbIdP remains in memory until the asynchronous call completes.

Comments

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbSelectPhonebook()

TelPhbSelectPhonebook Function ^TOP^

Purpose

Make the specified phone book the currently selected phone book.

Declared In

TelephonyMgr.h

Prototype 

Err TelPhbSelectPhonebook(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt8 iPhbId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iPhbId
The identifier of the phone book that you want selected as the current phone book. This must be one of the Phone Book Type Constants.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode
errNone upon success or an error code upon failure.
transId
The transaction ID of the operation.
paramP
Points to the unsigned integer value passed to this function in the iPhbId parameter.
functionId
kTelPhbSelectPhonebookMessage

Comments

Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPhbGetAvailablePhonebooks(), TelPhbGetSelectedPhonebook()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index