|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
-> |
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. |
The TelPhbGetEntryCount function uses the TelPhbGetEntryCountType structure to return information about the entries in the currently selected phone book.
typedef struct _TelPhbGetEntryCountType { UInt16 slots; UInt16 count; } TelPhbGetEntryCountType;
<- |
slots |
The total number of entry slots available in the phone book. |
c |
count |
The number of filled slots in the phone book. |
The TelPhbGetEntryMaxSizes function uses the TelPhbGetEntryMaxSizesType structure to return size information about the entries in the currently selected phone book.
typedef struct _TelPhbGetEntryMaxSizeType { UInt8 fullNameMaxSize; UInt8 dialNumberMaxSize; } TelPhbGetEntryMaxSizesType;
<- |
fullNameMaxSize |
The largest size of any fullName field in the phone book. |
<- |
dialNumberMaxSize |
The largest size of any dialNumber field in the phone book. |
This section describes the constants used with the phone book service set of the telephony API.
The phone book type constants specify the type of phone book that is currently selected.
This section describes the functions used with the phone book service set of the telephony API.
Add or replace an entry in the currently selected phone book.
Err TelPhbAddEntry(UInt16 iRefnum, TelAppID iAppId, TelPhbEntryType *iEntryP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 |
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.
Implemented only if 4.0 New Feature Set is present.
TelPhbDeleteEntry, TelPhbSelectPhonebook
Deletes an entry from the currently selected phone book.
Err TelPhbDeleteEntry(UInt16 iRefnum, TelAppID iAppId, UInt16 iEntryIndex, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelPhbAddEntry, TelPhbSelectPhonebook
Retrieve the list of all phone books available on the phone.
Err TelPhbGetAvailablePhonebooks(UInt16 iRefnum, TelAppID iAppId, TelPhbGetAvailablePhonebooksType *ioParamP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 |
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.
Implemented only if 4.0 New Feature Set is present.
Retrieve a range of entries from the currently selected phone book.
Err TelPhbGetEntries(UInt16 iRefnum, TelAppID iAppId, TelPhbGetEntriesType *ioParamP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 |
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.
Implemented only if 4.0 New Feature Set is present.
TelPhbGetEntry, TelPhbSelectPhonebook
Retrieve one entry from the currently selected phone book.
Err TelPhbGetEntry(UInt16 iRefnum, TelAppID iAppId, TelPhbEntryType *ioEntryP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 |
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.
Implemented only if 4.0 New Feature Set is present.
TelPhbGetEntries, TelPhbSelectPhonebook
Retrieve the total number of entries, and the number of filled entries in the currently selected phone book.
Err TelPhbGetEntryCount(UInt16 iRefnum, TelAppID iAppId, TelPhbGetEntryCountType *oParamP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 |
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.
Implemented only if 4.0 New Feature Set is present.
Retrieves the maximum buffer sizes of any entries in the currently selected phone book.
Err TelPhbGetEntryMaxSizes(UInt16 iRefnum, TelAppID iAppId, TelPhbGetEntryMaxSizesType *oParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oParamP | A pointer to a TelPhbGetEntryMaxSizesType 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. |
Returns errNone if the function was successful or returns an error code if not successful.
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 TelPhbGetEntryMaxSizesType structure passed to this function in the oParamP parameter. |
functionId |
kTelPhbGetEntryMaxSizesMessage |
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 TelPhbGetEntryMaxSizesType structure referenced by oParamP.
Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelPhbGetEntries, TelPhbGetEntry
Retrieve the ID of the currently selected phone book.
Err TelPhbGetSelectedPhonebook(UInt16 iRefnum, TelAppID iAppId, UInt8 *oPhbIdP, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Make the specified phone book the currently selected phone book.
Err TelPhbSelectPhonebook(UInt16 iRefnum, TelAppID iAppId, UInt8 iPhbId, UInt16 *ioTransIdP);
-> 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. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
Before using this function, you should verify that it is available by calling the TelIsPhbServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelPhbGetAvailablePhonebooks, TelPhbGetSelectedPhonebook
|