|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Note that the first five fields of the TelEventType structure are the same as the first five fields of the EventType structure, which is described in Chapter 3, "Palm OS Events."
|
<- |
state |
Filled in with one of the Telephone Call State Constants, which indicates the current state of the telephone call. |
<- |
callType |
Filled in with one of the Telephone Call Type Constants, which indicates the call type of the current telephone call. |
<- |
callServiceType |
Filled in with one of the Telephone Call Service Type Constants, which indicates the call service type of the current telephone call. |
<-> |
numberSize |
The size of the number string buffer. When the structure is used as an input parameter, this is the allocated size, in bytes, of the buffer. Upon return, this is the actual size of the string, including the null terminator character. If the number buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error. |
<- |
number |
A buffer into which the telephone number string is stored. When the structure describes an incoming telephone call, this is the incoming telephone number. When the structure describes an outgoing telephone call, this is the telephone number that has been called. Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
The TelInfGetInformation function uses the TelInfGetInformationType structure to retrieve information about the phone with which you are communicating.
typedef struct _TelInfGetInformationType { UInt8 infoType; UInt8 size; UInt8 *value; } TelInfGetInformationType;
-> |
infoType |
The type of information to retrieve. This must be one of the Information Type Constants. |
<-> |
size |
The size of the value buffer. When the structure is used as an input parameter, this is the allocated size, in bytes, of the buffer. Upon return, this is the actual size of the buffer. If the value buffer is too small to contain all of the retrieved information, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error. |
<- |
value |
A buffer into which the information is stored. |
You use the TelOemCallType to specify a TelOemCall function.
typedef struct _TelOemCallType { UInt32 OemID; UInt8 funcID; void *paramP; } TelOemCallType;
The TelSendCommandString function uses the TelSendCommandStringType structure to send a command string.
typedef struct _TelSendCommandStringType { Char *commandString; Char *resultString; UInt16 resultSize; UInt32 timeOut; } TelSendCommandStringType;
The TelSndPlayKeyTone function uses the TelSndPlayKeyToneType structure to specify a key tone.
typedef struct _TelSndPlayKeyToneType { UInt8 keycode; UInt8 type; } TelSndPlayKeyToneType;
-> |
keycode |
The keycode of the key tone to play. This must be one of the Keycode Constants. |
-> |
type |
The tone type. This must be one of the Key Sound Type Constants. |
This section describes the data structures used with the basic services portion of the telephony API, which include the following constant types:
Telephone Call State Constants
Telephone Call Service Type Constants
The battery status constants provide information about the phone's battery.
The TelCallStateType structure uses the telephone call state constants to encode the current state of the connected telephone call.
The TelCallStateType structure uses the telephone call type constants to encode the type of the current telephone call.
Constant |
Value |
Description |
---|---|---|
kTelCallTypeOutgoing |
0x00 |
An outgoing telephone call. |
kTelCallTypeIncoming |
0x01 |
An incoming telephone call. |
The TelCallStateType structure uses the telephone call service type constants to encode the service type of the current telephone call.
Constant |
Value |
Description |
---|---|---|
kTelCallServiceVoice |
0x00 |
A voice telephone call. |
kTelCallServiceData |
0x01 |
A data telephone call. |
The telephony manager functions return the error code constants shown in the following table to indicate their status.
The TelInfGetformationType structure uses the information type constants to encode the type of information to retrieve about the phone.
Constant |
Value |
Description |
---|---|---|
kTelInfPhoneBrand |
0 |
The brand name of the phone. |
kTelInfPhoneModel |
1 |
The model number of the phone. |
kTelInfPhoneRevision |
2 |
The revision number of the phone. |
The TelSndPlayKeyToneType structure uses the keycode constants to specify the key tone to play.
The TelSndPlayKeyToneType structure uses the key sound type constants to specify how the tone is played.
Constant |
Value |
Description |
---|---|---|
kTelSndSingleTone |
0x00 |
Play the key sound as a single tone. |
kTelSndMultiTones |
0x01 |
Play the key sound as a multiple tones. |
The message identifier constants are used with asynchronous calls to identify which telephony function is being or has been called. The TelMessages enumeration defines a constant for each function name.
Each message identifier constant has the form:
kfunctionNameMessage
where functionName is replaced by a function name.
The following table shows examples of message identifier constants. For a complete list, see the TelephonyMgr.h file.
Constant |
Function |
---|---|
kTelGetCallStateMessage |
|
kTelNwkSelectNetworkMessage |
|
kTelSmsReadMessageMessage |
The service set constants specify a set of API services.
This section describes the functions used with the basic services portion of the telephony API.
Cancels an asynchronous function call.
Err TelCancel(UInt16 iRefnum, TelAppID iAppId, UInt16 iTransId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iTransId | The transaction ID associated with the function that you are cancelling. |
<-> 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 call was successfully cancelled. Returns the telErrCommandFailed error code if the function call could not be cancelled.
The following fields are updated in the TelEventType event that is sent when the operation completes:
This function cancels a pending asynchronous function call. You can cancel any asynchronous call except for an asynchronous call to the TelCancel function.
The function call that is cancelled returns the telErrUserCancel error code.
Implemented only if 4.0 New Feature Set is present.
Err TelClose(UInt16 iRefnum, TelAppID iAppId);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
Returns an error code, or error none if the library was successfully closed. If the library is currently being used by another application, this function returns the telErrLibStillInUse error code.
Call this function when you are done with the telephony manager. You can only use this function synchronously.
If no other application is using the telephony manager, this function stops the Telephony task and releases any resources used by the telephony manager.
Closes down communications with the connected phone.
Err TelClosePhoneConnection(UInt16 iRefnum, TelAppID iAppId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 |
A NULL pointer. |
functionId |
kTelUrqClosePhoneConnectionMessage |
Call this function when you have finished communications with the phone and are ready to disconnect from it.
Implemented only if 4.0 New Feature Set is present.
Retrieves the current telephone call state information.
Err TelGetCallState(UInt16 iRefnum, TelAppID iAppId, TelGetCallStateType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelCallStateType structure that describes the state of the current telephone call. |
On input, the numberSize field of this structure specifies the allocated size of the number buffer. Upon return, the numberSize field specifies the actual size of the telephone number, even if it 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 TelCallStateType structure passed to this function in the ioCallState parameter. |
functionId |
kTelGetCallStateMessage |
This function retrieves information about the current telephone call state of the connection with the phone, and stores that information into the supplied TelCallStateType structure.
The current incoming or outgoing telephone call number is stored into the number field of the TelCallStateType structure referenced by ioCallStateP. If the number field buffer is too small to contain the complete telephone number, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The numberSize field of the structure is always updated to contain the actual size of the complete telephone number.
Implemented only if 4.0 New Feature Set is present.
TelSpcAcceptCall, TelSpcCallNumber
Retrieves events for applications that use the telephony manager.
void TelGetEvent(UInt16 iRefnum, TelAppID iAppId, EventPtr oEventP, Int32 iTimeOut);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oEventP | A pointer to a TelEventType structure. Upon return, the structure contains the event information, which you should use as described in the Comments section. |
-> iTimeout | Maximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely). |
This function retrieves both telephony and standard Palm OS® events. You must call this function to retrieve events in any application that is running in the UI task and using the telephony manager.
Upon return from this function, you need to test the type of the event by examining the oEventP->type field. If the event type is a telephony event, then you need to cast the pointer as follows to access the fields:
TelEventType *telEventP = (TelEventType *)oEventP;
This function calls both the EvtGetEvent and TelGetTelephonyEvent functions to retrieve the next event for your application.
Implemented only if 4.0 New Feature Set is present.
EvtGetEvent, TelGetTelephonyEvent
Retrieves telephony events only.
void TelGetTelephonyEvent(UInt16 iRefnum,
TelAppID iAppId, EventPtr oEventP,
Int32 iTimeOut);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oEventP | A pointer to a TelEventType structure. Upon return, the structure contains the event information. |
-> iTimeout | Maximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely). |
Use this function instead of the TelGetEvent function when you only want to process telephony events.
Implemented only if 4.0 New Feature Set is present.
Retrieve brand, model, and revision information for the phone.
Err TelInfGetInformation(UInt16 iRefnum,
TelAppID iAppId,
TelInfGetInformationType *ioParamP,
UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelInfGetformationType structure. |
On input, the infoType field of the structure contains the type of information that you want retrieved. The size field of this structure specifies the allocated size of the value buffer. Upon return, the size field specifies the actual size of the information that was retrieved, even if it 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 TelInfGetformationType structure passed to this function in the ioInfoP parameter. |
functionId |
kTelInfGetInformationMessage |
Call this function to retrieve information about the currently connected phone.
The retrieved information is stored into the value field of the TelInfGetformationType referenced by ioInfoP structure. If the value field buffer is too small to contain the complete information, the value is truncated and this function returns the telErrBufferSize error. The size field of the structure is always updated to contain the actual size of the retrieved information.
Before using this function, you should verify that it is available by calling the TelIsInfServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the configuration service set is available in the current environment.
TelIsCfgServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelCfgServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the configuration service set, which is the family of functions that begin with the TelCfg prefix.
The configuration service set functions are documented in Chapter 73, "Telephony SMS."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the data calls service set is available in the current environment.
TelIsDtcServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelDtcServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the data calls service set, which is the family of functions that begin with the TelDtc prefix.
The data calls service set functions are documented in Chapter 72, "Telephony Calls."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the emergency calls service set is available in the current environment.
TelIsEmcServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelEmcServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the emergency calls service set, which is the family of functions that begin with the TelEmc prefix.
The emergency calls service set functions are documented in Chapter 72, "Telephony Calls."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the information service set is available in the current environment.
TelIsInfServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelInfServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the information service set, which is the family of functions that begin with the TelInf prefix.
The information service set functions are documented in this chapter.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the network service set is available in the current environment.
TelIsNwkServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelNwkServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the network service set, which is the family of functions that begin with the TelNwk prefix.
The network service set functions are documented in Chapter 71, "Telephony Network."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the OEM service set is available in the current environment.
TelIsOemServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelOemServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the OEM service set, which is the family of functions that begin with the TelOem prefix.
The OEM service set functions are documented in this chapter.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the phone book service set is available in the current environment.
TelIsPhbServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelPhbServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the phone book service set, which is the family of functions that begin with the TelPhb prefix.
The phone book service set functions are documented in Chapter 74, "Telephony Phone Book."
Implemented only if 4.0 New Feature Set is present.
Determines if a phone is connected.
Err TelIsPhoneConnected(UInt16 iRefnum, TelAppID iAppId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 |
A NULL pointer. |
functionId |
kTelUrqIsPhoneConnectedMessage |
Call this function to determine if there is currently a phone connected.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the power services set is available in the current environment.
TelIsPowServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelPowServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the power service set, which is the family of functions that begin with the TelPow prefix.
The power service set functions are documented in this chapter.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the Short Message Service (SMS) service set is available in the current environment.
TelIsSmsServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelSmsServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the SMS service set, which is the family of functions that begin with the TelSms prefix.
The SMS service set functions are documented in Chapter 73, "Telephony SMS."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the sound service set is available in the current environment.
TelIsSndServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelSndServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the sound service set, which is the family of functions that begin with the TelSnd prefix.
The sound service set functions are documented in this chapter.
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the speech telephone call service set is available in the current environment.
TelIsSpcServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelSpcServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the speech telephone call service set, which is the family of functions that begin with the TelSpc prefix.
The speech telephone call service set functions are documented in Chapter 72, "Telephony Calls."
Implemented only if 4.0 New Feature Set is present.
A macro that determines if the security service set is available in the current environment.
TelIsStyServiceAvailable (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available, or an error code if not.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
kTelStyServiceId |
functionId |
kTelUrqIsServiceAvailableMessage |
You need to call this macro before calling any function in the security service set, which is the family of functions that begin with the TelSty prefix.
The security service set functions are documented in Chapter 71, "Telephony Network."
Implemented only if 4.0 New Feature Set is present.
Determines if the currently selected driver matches the connected phone.
Err TelMatchPhoneDriver(UInt16 iRefnum, TelAppID iAppId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 |
A NULL pointer. |
functionId |
kTelUrqMatchPhoneDriverMessage |
Implemented only if 4.0 New Feature Set is present.
Pass a call to an OEM function.
Err TelOemCall(UInt16 iRefnum, TelAppID iAppId, TelOemCallType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelOemCallType structure that contains information about the OEM function call. |
<-> 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 |
matches the output value of the ioTransIdP parameter |
functionId |
matches the function ID in the TelOemCallType structure passed to this function in the ioParamP parameter |
paramId |
points to the TelOemCallType structure passed to this function in the ioParamP parameter |
Call this function to send a request to an OEM function. The calling function and the OEM function are responsible for coordinating the parameter block that is passed in the TelOemCallType structure.
Before using this function, you should verify that it is available by calling the TelIsOemServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Open the telephony manager API to initialize telephony services and launch the telephony task.
Err TelOpen(UInt16 iRefnum, UInt32 iVersnum, TelAppID *oAppIdP);
-> iRefnum | The telephony manager library reference number. |
-> iVersnum | The version number of the shared library for which your application was developed. |
<- oAppIdP | A pointer to an application ID value. Upon return, this is the application ID that you supply as a parameter to the any other telephony functions that you call. |
Returns errNone if the function was successful or returns an error code if not successful. The following errors can occur:
the telephony task could not be found (telErrTTaskNotFound)
the telephony task could not be launched (telErrTTaskNotRunning)
the phone driver could not be found
the shared library version is not valid
You can only call this function synchronously. You must call this function before calling any other telephony manager functions.
You can specify the current version of the shared library by using the kTelMgrVersion constant as the value of the iVersnum parameter.
Implemented only if 4.0 New Feature Set is present.
Open communications with the connected phone.
Err TelOpenPhoneConnection(UInt16 iRefnum, TelAppID iAppId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 |
A NULL pointer. |
functionId |
kTelUrqOpenPhoneConnectionMessage |
Implemented only if 4.0 New Feature Set is present.
Retrieves the status of the phone's battery.
Err TelPowGetBatteryStatus(UInt16 iRefnum, TelAppID iAppId, UInt8 *oStatusP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oStatusP | A pointer to an unsigned byte value. Upon return, this is the battery status value, which is one of the Battery Status 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 TelIsPowServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve the current level of the phone battery, as a percentage value.
Err TelPowGetPowerLevel(UInt16 iRefnum, TelAppID iAppId, UInt8 *oPowerP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oPowerP | A pointer to an unsigned byte value. Upon return, this is the battery percentage value. |
<-> 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:
The returned percentage value is an integer value between 0 and 100.
Before using this function, you should verify that it is available by calling the TelIsPowServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Err TelPowSetPhonePower(UInt16 iRefnum, TelAppID iAppId, Boolean iPowerOn);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iPowerOn | Set to true to turn the phone on, and set to false to turn the phone off. |
Returns errNone if the function was successful and an error code if not.
This function can only be called synchronously.
Before using this function, you should verify that it is available by calling the TelIsPowServiceAvailable macro.
This function corresponds to the kTelPowSetPhonePowerMessage function ID value.
Implemented only if 4.0 New Feature Set is present.
Sends a command string to the phone or to the network.
Err TelSendCommandString(UInt16 iRefnum, TelAppID iAppId, TelSendCommandStringType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a command string structure of type TelSendCommandStringType. |
<-> 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 TelSendCommandStringType structure passed to this function in the ioParam parameter. |
functionId |
Matches the function ID in the TelOemCallType referenced by the ioParamP structure. |
Implemented only if 4.0 New Feature Set is present.
Mute or un-mute an active telephone call.
Err TelSndMute(UInt16 iRefnum, TelAppID iAppId, Boolean iMuteOn, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iMuteOn | Set to true to mute the telephone call, or set to false to unmute the telephone call. |
<-> 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 TelIsSndServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Play a keytone sound on the phone.
Err TelSndPlayKeyTone(UInt16 iRefnum, TelAppID iAppId, TelSndPlayKeyToneType *iParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iParamP | A pointer to a TelSndPlayKeyToneType structure that describes the tone to play. |
<-> 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 TelSndPlayKeyToneType structure passed to this function in the iKeyToneP parameter. |
functionId |
kTelSndPlayKeyTone |
Before using this function, you should verify that it is available by calling the TelIsSndServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Stop the playing of a keytone sound on the phone.
Err TelSndStopKeyTone(UInt16 iRefnum, TelAppID iAppId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 |
A NULL pointer. |
functionId |
kTelSndStopKeyToneMessage |
Before using this function, you should verify that it is available by calling the TelIsSndServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
This section describes the functions that you can call to determine if a specific feature or function is supported in the current operating environment.
Determines if the specified function is supported.
TelIs<FunctionName>Supported (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 specified function is supported.
The following fields are updated in the TelEventType event that is sent when the operation completes:
This is a family of synchronous macros that test if a specific function is available in the current environment.
To use the macro, substitute a function name for the <FunctionName> portion of the macro name. You can substitute any Telephony Manager function name; for a complete list of the Telephony Manager functions, see "Summary of Telephony Manager" in Palm OS Programmer's Companion, vol. II, Communications.
For example, to determine if the TelNwkGetSignalLevel function is available in the current environment, call the TelIsNwkGetSignalLevelSupported macro.
This macro corresponds to the kTelUrqIsFunctionSupportedMessage function ID value.
Implemented only if 4.0 New Feature Set is present.
Determines if the specified service set is available.
TelIs<ServiceSet>Available (iRefnum, iAppId, ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> 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 service set is available.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone if the service set is available, or an error code if not. |
transId |
The transaction ID of the operation. |
paramP |
The service ID of the service set for which you are testing. For example, if you call TelIsCfgServiceAvailable, the value of this field is kTelCfgServiceId. The service IDs are described in Service Set Constants. |
functionId |
kTelUrqIsServiceAvailableMessage |
This is a family of synchronous macros that test if a specific service set is available. You must call the appropriate set availability function before calling a function in the set.
You can call these specific macros to determine if the service set is available:
TelIsCfgServiceAvailable to determine if the configuration service set is available.
TelIsDtcServiceAvailable to determine if the data calls service set is available.
TelIsEmcServiceAvailable to determine if the emergency calls service set is available.
TelIsInfServiceAvailable to determine if the information service set is available.
TelIsNwkServiceAvailable to determine if the network service set is available.
TelIsOemServiceAvailable to determine if the OEM service set is available.
TelIsPhbServiceAvailable to determine if the phone book service set is available.
TelIsPowServiceAvailable to determine if the power service set is available.
TelIsSmsServiceAvailable to determine if the SMS service set is available.
TelIsSndServiceAvailable to determine if the sound service set is available.
TelIsSpcServiceAvailable to determine if the speech calls service set is available.
TelIsStyServiceAvailable to determine if the security service set is available.
Each of these macros corresponds to the kTelUrqIsServiceSupportedMessage function ID value.
Implemented only if 4.0 New Feature Set is present.
|