Telephony Security and Configuration
 

 < 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelCfgGetPhoneNumberType structure that is filled in with the dial telephone number.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelCfgGetSmsCenterType structure that is filled in with the dial telephone number.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iDialNumberPA pointer to the null-terminated dial telephone number string for the SMS service center.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iParamPA pointer to a TelStyChangeAuthenticationType structure that contains the old and new authentication code values.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iCodePA pointer to the null-terminated authentication code string to send to the phone.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oStatePA pointer to an unsigned byte value. Upon return, this is the authentication state, which is one of the Authentication State Constants.
<-> ioTransIdPSet 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