|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Network Search Mode Constants
The network search mode constants describe the search mode used to find a network.
Telephony Network Functions
This section describes the data structures used with the telephony network service set portion of the telephony API.
|
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelNwkGetLocationType structure. |
On input, 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 location string, 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 TelNwkGetLocationType passed to this function in the ioParamP parameter. |
functionId |
kTelNwkGetLocationMessage |
The location information string is stored into the value field of the TelNwkGetLocationType structure referenced by ioParamP. If the value buffer is too small to contain the complete string, 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 string.
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Returns the name of a registered network.
Err TelNwkGetNetworkName(UInt16 iRefnum, TelAppID iAppId, TelNwkGetNetworkNameType* ioParamP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelNwkGetNetworkNameType structure that stores the network name. |
On input, 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 name string, 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 TelNwkGetNetworkNameType passed to this function in the ioParamP parameter. |
functionId |
kTelNwkGetNetworkNameMessage |
The network name string is stored into the value field of the structure. If the value field buffer in the TelNwkGetNetworkNameType structure is too small to contain the complete string, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The size field is always updated to contain the actual size of the complete string.
The string that is returned in the value field of the structure referenced by ioParamP is network dependent.
On a GSM network, the result string is compliant with the AT 07.07 European Telecommunications Standards Institute (ETSI) standard for COPS and CREG commands. The result string contains the following elements:
The network type, as returned by the TelNwkGetNetworkType function, and followed by a semicolon (';') character.
The network operator, using the following syntax:
<area code> ';' <network registration>
The <area code> value is the value retrieved by issuing the AT+CREG? command.
The <network registration> value is the value retrieved by issuing the AT+CREG? command.
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelNwkGetNetworks, TelNwkGetSelectedNetwork
Retrieves information about the registered networks.
Err TelNwkGetNetworks(UInt16 iRefnum, TelAppID iAppId, TelNwkGetNetworksType* ioParamP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelNwkGetNetworksType structure that stores the network IDs. On input, the size field of this structure contains the size, in elements, of the networkIdP array field. |
Upon return, the networkIdP array contains the IDs of the registered networks, and the size field contains the number of IDs in the array. |
<-> 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 TelNwkGetNetworksType passed to this function in the ioParamP parameter. |
functionId |
kTelNwkGetNetworkCountMessage |
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelNwkGetNetworkName, TelNwkGetNetworks
Retrieve the type of the selected network.
Err TelNwkGetNetworkType(UInt16 iRefnum, TelAppID iAppId, UInt8* oTypeP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oTypeP | A pointer to an unsigned byte value. Upon return, this is the network type. This is one of Network Type 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 TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Returns the current network search mode.
Err TelNwkGetSearchMode(UInt16 iRefnum, TelAppID iAppId, UInt8* oModeP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oModeP | A pointer to an unsigned byte value. Upon return, this is the type of search mode that is currently being used. This is one of the Network Search Mode 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 TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve the network identifier of the currently selected network.
Err TelNwkGetSelectedNetwork(UInt16 iRefnum, TelAppID iAppId, UInt32* oNetworkIdP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oNetworkIdP | A pointer to an unsigned integer value. Upon return, this is the identifier of the currently selected network. |
<-> 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 TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelNwkGetNetworkName, TelNwkGetNetworks, TelNwkSelectNetwork
Retrieve the selected network carrier signal level.
Err TelNwkGetSignalLevel(UInt16 iRefnum, TelAppID iAppId, UInt8* oSignalP, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oSignalP | A pointer to an unsigned byte value. Upon return, this is an indication of the signal level in decibels per milliwatt (dBm). The values are explained in the Comments section. |
<-> 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:
This function sets the value of the variable referenced by oSignalP to an integer value that indicates the signal strength in dBm.
The following table describes the signal strength values.
Signal level value |
dBm value |
---|---|
0 |
£ 113 dBm |
1 |
111 dBm |
2 to 30 |
109 dBm to 53 dBm |
31 |
51 dBm |
99 |
unknown or undetectable |
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Select a network to use from among the set of registered networks.
Err TelNwkSelectNetwork(UInt16 iRefnum, TelAppID iAppId, UInt32 iNetworkId, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iNetworkId | The identifier of the network to select. |
<-> 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 TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelNwkGetNetworkName, TelNwkGetNetworks, TelNwkGetSelectedNetwork
Sets the search mode used to find a network.
Err TelNwkSetSearchMode(UInt16 iRefnum, TelAppID iAppId, UInt8 iMode, UInt16* ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> iMode | The search mode to use. This must be one of the Network Search Mode 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 TelIsNwkServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
|