Part III: Communications

74 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

TelCfgGetPhoneNumber

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 73, "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 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(
   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

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(
   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

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(
   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

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(
   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

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(
   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

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(
   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

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()