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

74    Telephony Security and Configuration

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 73, "Telephony Basic Services."

This chapter describes:

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

Telephony Security and Configuration Data Structures ^TOP^

This section describes the data structures used with the telephony security and configuration service sets portion of the telephony API.

TelCfgGetPhoneNumberType Struct ^TOP^

Purpose

The TelCfgGetPhoneNumber() function uses a TelCfgGetPhoneNumberType structure to retrieve the connected phone dial number.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelCfgGetPhoneNumberType {
UInt8 size;
Char *value;
} TelCfgGetPhoneNumberType

Fields

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.

TelCfgGetSmsCenterType Struct ^TOP^

Purpose

The TelCfgGetSmsCenter() function uses a TelCfgGetSmsCenterType structure to retrieve the SMS service center dial number.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelCfgGetSmsCenterType {
UInt8 size;
Char *value;
} TelCfgGetSmsCenterType

Fields

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.

TelStyChangeAuthenticationType Struct ^TOP^

Purpose

You use the TelStyChangeAuthenticationType to change an authentication code with the TelStyChangeAuthenticationCode() function.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelStyChangeAuthenticationType {
UInt8 codeId;
Char *oldCode;
Char *newCode;
} TelStyChangeAuthenticationType

Fields

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 ^TOP^

This section describes the constants used with the telephony security and configuration service sets of the telephony API.

Authentication State Constants ^TOP^

Purpose

The authentication state constants describe the current authentication state of the mobile unit connection.

Declared In

TelephonyMgr.h

Constants

#define kTelStyReady 0
No additional security information is expected.
#define kTelStyPin1CodeId 1
The PIN1 code is expected.
#define kTelStyPin2CodeId 2
The PIN2 code is expected.
#define kTelStyPuk1CodeId 3
The PUK1 code is expected.
#define kTelStyPuk2CodeId 4
The PUK2 code is expected.

#define kTelStyPhoneToSimCodeId 5

The phone-to-SIM code is expected.

#define 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 kTelStyFirstOemCodeId+2.

Telephony Security and Configuration Functions ^TOP^

This section describes the data structures used with the telephony security and configuration service sets portion of the telephony API.

TelCfgGetPhoneNumber Function ^TOP^

Purpose

Retrieve the connected telephone number.

Declared In

TelephonyMgr.h

Prototype

Err TelCfgGetPhoneNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   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()

TelCfgGetSmsCenter Function ^TOP^

Purpose

Retrieve the SMS service center dial telephone number.

Declared In

TelephonyMgr.h

Prototype

Err TelCfgGetSmsCenter(
   UInt16iRefnum,
   TelAppIDiAppId,
   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()

TelCfgSetSmsCenter Function ^TOP^

Purpose

Set the SMS service center dial telephone number.

Declared In

TelephonyMgr.h

Prototype

Err TelCfgSetSmsCenter(
   UInt16iRefnum,
   TelAppIDiAppId,
   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()

TelStyChangeAuthenticationCode Function ^TOP^

Purpose

Change the value of an authentication code. Note that you can only use this function with GSM networks.

Declared In

TelephonyMgr.h

Prototype

Err TelStyChangeAuthenticationCode(
   UInt16iRefnum,
   TelAppIDiAppId,
   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()

TelStyEnterAuthenticationCode Function ^TOP^

Purpose

Enter the authentication code for which the phone is currently waiting. Note that you can only use this function with GSM networks.

Declared In

TelephonyMgr.h

Prototype

Err TelStyEnterAuthenticationCode(
   UInt16iRefnum,
   TelAppIDiAppId,
   constChar*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()

TelStyGetAuthenticationState Function ^TOP^

Purpose

Returns the current state of user authentication.

Declared In

TelephonyMgr.h

Prototype

Err TelStyGetAuthenticationState(
   UInt16iRefnum,
   TelAppIDiAppId,
   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()