< Home < Developers < Development Support < Documentation

## 70 Telephony Security and Configuration

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 70 Telephony Security and Configuration Telephony Security and Configuration Data Structures TelCfgGetPhoneNumberType TelCfgGetSmsCenterType TelStyChangeAuthenticationType Telephony Security and Configuration Constants Authentication State Constants Telephony Security and Configuration Functions TelCgfGetPhoneNumber TelCfgGetSmsCenter TelCfgSetSmsCenter TelStyChangeAuthenticationCode TelStyEnterAuthenticationCode TelStyGetAuthenticationState |  |  |  | This chapter describes the telephony security and configuration service sets of the telephony API. For more information about the telephony manager basic services and the different service sets, see Chapter 69, "Telephony Basic Services." This chapter describes: Telephony Security and Configuration Data Structures Telephony Security and Configuration Constants Telephony Security and Configuration Functions For more information about using the telephony manager, see Chapter 8, "Telephony Manager" in the Palm OS Programmer's Companion. ## Telephony Security and Configuration Data Structures This section describes the data structures used with the telephony security and configuration service sets portion of the telephony API. ## New TelCfgGetPhoneNumberType The TelCgfGetPhoneNumber function uses a TelCfgGetPhoneNumberType structure to retrieve the connected phone dial number.
    typedef struct _TelCfgGetPhoneNumberType
      UInt8    size;
      Char*    value;
    } TelCfgGetPhoneNumberType;
#### Field Descriptions #####
<-> | 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 value buffer. Upon return, this is the actual size of the string, including the null terminator character. If the value buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.
<- | value | A buffer into which the dial number is stored. 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.
## New TelCfgGetSmsCenterType The TelCfgGetSmsCenter function uses a TelCfgGetSmsCenterType structure to retrieve the SMS service center dial number.
    typedef struct _TelCfgGetSmsCenterType
      UInt8   size;
      Char*   value;
    } TelCfgGetSmsCenterType;
#### Field Descriptions #####
<-> | 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 value buffer. Upon return, this is the actual size of the string, including the null terminator character. If the value buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.
<- | value | A buffer into which the dial number is stored. 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.
## New TelStyChangeAuthenticationType You use the TelStyChangeAuthenticationType to change an authentication code with the TelStyChangeAuthenticationCode function.
    typedef struct _TelStyChangeAuthenticationType
    {
      UInt    codeId;
      Char*   oldCode;
      Char*   newCode;
    } TelStyChangeAuthenticationType;
#### Field Descriptions #####
-> | codeId | The ID of the authentication code to change.
-> | oldCode | The previous value of the code.
-> | newCode | The new value of the code.
## Telephony Security and Configuration Constants This section describes the constants used with the telephony security and configuration service sets of the telephony API. ## Authentication State Constants The authentication state constants describe the current authentication state of the mobile unit connection. #####
Constant | Value | Description
--- | --- | ---
kTelStyReady | 0 | No additional security information is expected.
kTelStyPin1CodeId | 1 | The PIN1 code is expected.
kTelStyPin2CodeId | 2 | The PIN2 code is expected.
kTelStyPuk1CodeId | 3 | The PUK1 code is expected.
kTelStyPuk2CodeId | 4 | The PUK2 code is expected.
kTelStyPhoneToSimCodeId | 5 | The phone-to-SIM code is expected.
kTelStyFirstOemCodeId | 6 | An OEM code is expected. The constant kTelStyFirstOemCodeId specifies the first OEM authentication code. You can specify additional OEM codes by incrementing this value. For example, to specify the third OEM authentication code, use the following:
    kTelStyFirstOemCodeId+2
## Telephony Security and Configuration Functions This section describes the data structures used with the telephony security and configuration service sets portion of the telephony API. ## New TelCgfGetPhoneNumber #### Purpose Retrieve the connected telephone number. #### Prototype Err TelCfgGetPhoneNumber(UInt16 iRefnum, TelAppID iAppId, TelCfgGetPhoneNumberType* 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 TelCfgGetPhoneNumberType structure that is filled in with the dial telephone number.
#####
<-> 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 TelCfgGetPhoneNumberType structure passed to this function in the ioParamP parameter.
functionId | kTelCfgGetPhoneNumberMessage
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 connected dial telephone number is stored into the value field of the TelCfgGetPhoneNumberType structure referenced by ioParamP. If the value 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 size field of the structure is always updated to contain the actual size of the complete telephone number. Before using this function, you should verify that it is available by calling the TelIsCfgServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelCfgSetSmsCenter, TelSmsSendMessage ## New TelCfgGetSmsCenter #### Purpose Retrieve the SMS service center dial telephone number. #### Prototype Err TelCfgGetSmsCenter(UInt16 iRefnum, TelAppID iAppId, TelCfgGetSmsCenterType* 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 TelCfgGetSmsCenterType structure that is filled in with the dial telephone number.
#####
<-> 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 TelCfgGetSmsCenterType structure passed to this function in the ioParamP parameter.
functionId | kTelCfgGetSmsCenterMessage
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 service center dial telephone number is stored into the value field of the TelCfgGetSmsCenterType structure referenced by ioParamP. If the value 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 size field of the structure is always updated to contain the actual size of the complete telephone number. Before using this function, you should verify that it is available by calling the TelIsCfgServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelCfgSetSmsCenter, TelSmsSendMessage ## New TelCfgSetSmsCenter #### Purpose Set the SMS service center dial telephone number. #### Prototype Err TelCfgSetSmsCenter(UInt16 iRefnum, TelAppID iAppId, const Char* iDialNumberP, UInt16* ioTransIdP); #### Parameters #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
-> iDialNumberP | A pointer to the null-terminated dial telephone number string for the SMS service center.
#####
<-> 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 string passed to this function in the iDialNumberP parameter.
functionId | kTelCfgSetSmsCenterMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by iDialNumberP remains in memory until the asynchronous call completes. #### Comments Before using this function, you should verify that it is available by calling the TelIsCfgServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelCfgGetSmsCenter, TelSmsSendMessage ## New TelStyChangeAuthenticationCode #### Purpose Change the value of an authentication code. Note that you can only use this function with GSM networks. #### Prototype Err TelStyChangeAuthenticationCode(UInt16 iRefnum, TelAppID iAppId, TelStyChangeAuthenticationType* iParamP, UInt16* ioTransIdP); #### Parameters #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
-> iParamP | A pointer to a TelStyChangeAuthenticationType structure that contains the old and new authentication code values.
#####
<-> 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 TelStyChangeAuthenticationType structure passed to this function in the iParamP parameter.
functionId | kTelStyChangeAuthenticationCodeMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by iParamP remains in memory until the asynchronous call completes. #### Comments Before using this function, you should verify that it is available by calling the TelIsStyServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelStyEnterAuthenticationCode ## New TelStyEnterAuthenticationCode #### Purpose Enter the authentication code for which the phone is currently waiting. Note that you can only use this function with GSM networks. #### Prototype Err TelStyEnterAuthenticationCode(UInt16 iRefnum, TelAppID iAppId, const Char* iCodeP, UInt16* ioTransIdP); #### Parameters #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
-> iCodeP | A pointer to the null-terminated authentication code string to send to the phone.
#####
<-> 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 string passed to this function in the iCodeP parameter.
functionId | kTelStyEnterAuthenticationCodeMessage
WARNING! When using this function asynchronously, you must ensure that the string referenced by iCodeP remains in memory until the asynchronous call completes. #### Comments Before using this function, you should verify that it is available by calling the TelIsStyServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelStyChangeAuthenticationCode, TelStyGetAuthenticationState ## New TelStyGetAuthenticationState #### Purpose Returns the current state of user authentication. #### Prototype Err TelStyGetAuthenticationState(UInt16 iRefnum, TelAppID iAppId, UInt8* oStateP, UInt16* ioTransIdP); #### Parameters #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<- oStateP | A pointer to an unsigned byte value. Upon return, this is the authentication state, which is one of the Authentication State 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 oStateP parameter.
functionId | kTelStyGetAuthenticationStateMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by oStateP remains in memory until the asynchronous call completes. #### Comments Before using this function, you should verify that it is available by calling the TelIsStyServiceAvailable macro. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TelStyEnterAuthenticationCode |