Telephony SMS
 

 < Home   < Developers   < Development Support   < Documentation

73 Telephony SMS


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part III: Communications

73 Telephony SMS

Telephony SMS Data Structures

TelSmsDateTimeType

TelSmsDeleteMessageType

TelSmsDeliveryAdvancedCDMAType

TelSmsDeliveryAdvancedGSMType

TelSmsDeliveryAdvancedTDMAType

TelSmsDeliveryMessageType

TelSmsExtensionType

TelSmsGetAvailableStorageType

TelSmsGetMessageCountType

TelSmsManualAckType

TelSmsMultiPartExtensionType

TelSmsNbsExtensionType

TelSmsReadMessagesType

TelSmsReadReportsType

TelSmsReadSubmittedMessagesType

TelSmsReportType

TelSmsSendMessageType

TelSmsSubmitAdvancedCDMAType

TelSmsSubmitAdvancedGSMType

TelSmsSubmitAdvancedTDMAType

TelSmsSubmitMessageType

TelSmsSubmittedMessageType

TelSmsUserExtensionType

Telephony SMS Constants

SMS Extension Type Constants

SMS Message Type Constants

SMS Message Transport Protocol Constants

SMS Storage ID Constants

SMS Data Coding Scheme Constants

SMS Message Urgency Constants

SMS Message Privacy Constants

Telephony SMS Functions

TelSmsDeleteMessage

TelSmsGetAvailableStorage

TelSmsGetDataMaxSize

TelSmsGetMessageCount

TelSmsGetSelectedStorage

TelSmsGetUniquePartId

TelSmsReadMessage

TelSmsReadMessages

TelSmsReadReport

TelSmsReadReports

TelSmsReadSubmittedMessage

TelSmsReadSubmittedMessages

TelSmsSelectStorage

TelSmsSendManualAcknowledge

TelSmsSendMessage

       

This chapter describes the telephony SMS service set 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 SMS Data Structures

Telephony SMS Constants

Telephony SMS Functions

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

Telephony SMS Data Structures

This section describes the data structures used with the SMS service set of the telephony API.

New TelSmsDateTimeType

Several of the other data structures used with the Telephony SMS functions include an TelSmsDateTimeType structure to store a date and time value.

typedef _TelSmsDateTimeType 
  Boolean    absolute; 
  UInt32     dateTime; 
} TelSmsDateTimeType 

Field Descriptions

->
absolute
If true, the dateTime value is a PalmTM absolute time value, which is the number of seconds since 1/1/1904. If false, the dateTime value is relative to the current date and time.
->
dateTime
The date and time value.

If the absolute field is true, this is expressed as the number of seconds elapsed since 12:00 A.M. on January 1, 1904. This is the format returned by the TimGetSeconds function.

If the absolute field is false, this is expressed as the number of seconds elapsed from the current time.

New TelSmsDeleteMessageType

The TelSmsDeleteMessage function uses a TelSmsDeleteMessageType structure to specify the message to be deleted.

typedef struct _TelSmsDeleteMessageType 
  UInt8    messageType; 
  UInt16   index; 
} TelSmsDeleteMessageType; 

Field Descriptions

->
messageType
The message type. This is one of the SMS Message Type Constants.
->
index
The index of the SMS message in the phone's storage that is to be deleted. Note that the message is deleted from the storage area selected by a call to the TelSmsSelectStorage function.

Note that the index is zero-based.

New TelSmsDeliveryAdvancedCDMAType

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedCDMAType structure for CDMA messages.

typedef struct _TelSmsDeliveryAdvancedCDMAType 
{ 
  UInt8              messageType; 
  TelSmsDateTimeType validityPeriod; 
  UInt8              priority; 
  UInt8              privacy; 
  Boolean            alertOnDeliveryRequest; 
  Boolean            manualAckRequest; 
  UInt8              voiceMessageNumber; 
  UInt8              callbackNumberSize; 
  Char               *callbackNumberAddress;  
  UInt8              languageIndicator; 
} TelSmsDeliveryAdvancedCDMAType; 

Field Descriptions


messageType
The type of the message. This must be one of the SMS Message Type Constants.

validityPeriod
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid.

priority
The message priority. This must be one of the SMS Message Urgency Constants.

privacy
The privacy type of the message. This must be one of the SMS Message Privacy Constants.

alertOnDeliveryRequest
true if the user is to be alerted upon delivery of this message, and false if not.

manualAckRequest
true if a reply is requested from the user, and false if not.

voiceMessageNumber


callbackNumberSize
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumberAddress string.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.

callbackNumberAddress
A buffer into which the callback number address string 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.

languageIndicator

New TelSmsDeliveryAdvancedGSMType

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedGSMType structure for GSM messages.

typedef struct _TelSmsDeliveryAdvancedGSMType 
{ 
  UInt16     protocolId; 
  Boolean    replyPath; 
  Char       *serviceCenterNumber; 
  UInt8      serviceCenterNumberSize; 
} TelSmsDeliveryAdvancedGSMType 

Field Descriptions

<-
protocolId
The protocol used for this message. This is one of the SMS Message Transport Protocol Constants.
<-
replyPath
If this value is set, then you use the serviceCenterNumber to reply to this message.

If this value is not set, you use the default service center provided by your network operator.
<->
serviceCenterNumber
A buffer into which the service center number string 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.
<->
seviceCenterNumberSize
When the structure is used as an input parameter, this is the allocated size, in bytes, of the serviceCenterNumber string.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.

New TelSmsDeliveryAdvancedTDMAType

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedTDMAType structure for TDMA messages.

typedef struct _TelSmsDeliveryAdvancedTDMAType 
{ 
  UInt8                messageType; 
  TelSmsDateTimeType   validityPeriod; 
  UInt8                priority; 
  UInt8                privacy; 
  Boolean              alertOnDeliveryRequest; 
  Boolean              manualAckRequest; 
  UInt8                voiceMessageNumber; 
  UInt8                callbackNumberSize; 
  Char                 *callbackNumberAddress; 
  UInt8                languageIndicator; 
} TelSmsDeliveryAdvancedTDMAType; 

Field Descriptions


messageType
The type of the message. This must be one of the SMS Message Type Constants.

validityPeriod
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid.

priority
The message priority. This must be one of the SMS Message Urgency Constants.

privacy
The privacy type of the message. This must be one of the SMS Message Privacy Constants.

alertOnDeliveryRequest
true if the user is to be alerted upon delivery of this message, and false if not.

manualAckRequest
true if a reply is requested from the user, and false if not.

voiceMessageNumber


callbackNumberSize
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumberAddress string.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.

callbackNumberAddress
A buffer into which the callback telephone number address string 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.

languageIndicator

New TelSmsDeliveryMessageType

The TelSmsReadMessage function uses a TelSmsDeliveryMessageType structure to retrieve information about a delivered message.

typedef struct _TelSmsDeliveryMessageType 
{ 
  UInt16               version; 
  UInt16               index; 
  UInt32               messageIdentifier; 
  TelSmsDateTimeType   timeStamp; 
  UInt16               dataSize; 
  UInt8                *data; 
  UInt8                dataCodingScheme; 
  UInt8                originatingAddressSize; 
  Char                 *originatingAddress; 
  Boolean              otherToReceive; 
  Boolean              reportDeliveryIndicator; 
  UInt8                standardType; 
  
  union 
  { 
    TelSmsDeliveryAdvancedGSMType
                                 advancedGSM; 
    TelSmsDeliveryAdvancedCDMAType
                                  advancedCDMA; 
    TelSmsDeliveryAdvancedTDMAType
                                  advancedTDMA; 
  } advancedParams; 
  UInt8                extensionsCount; 
  TelSmsExtensionType  *extensionsP; 
} TelSmsDeliveryMessageType; 
  

Field Descriptions

->
version
The version of the SMS API associated with this message.
<->
index
Upon return, the SMS index of the message on the phone. This is a 0-based index.

This value is used for input only when calling the TelSmsReadMessage function to read one SMS at a time.
<-
messageIdentifier
The message identifier.
<-
timeStamp
The message time stamp. This is a TelSmsDateTimeType structure.
<->
dataSize
The size of the data buffer.

When the structure is used as an input parameter, this is the allocated size of the data buffer.

Upon return, this is the actual size of the message data. If the buffer is too small to contain the entire message, this field is assigned the entire length of the message, and the function using this structure generates a telErrBufferSize error.
<->
data
A buffer into which the retrieved data is stored.

Note that if this buffer is too small to contain the entire retrieved message, the end of the message is truncated and the function using this structure generates a telErrBufferSize error.
<-
dataCodingScheme
The coding scheme used for the data. This is one of the SMS Data Coding Scheme Constants.
<->
originatingAddressSize
The size of the originatingAddress buffer.

When the structure is used as an input parameter, this is the allocated size of the originatingAddress buffer.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.
<->
originatingAddress
A buffer into which the originating address string is stored.

Note that if this buffer is too small to contain the entire 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.
<-
otherToReceive
Indicates whether there are more messages waiting to be received from the service center to the mobile device.
<-
reportDeliveryIndicator
If true, indicates that the originating user has asked the network to send a delivery report.
<-
standardType
Indicates which field of the advancedParams union contains the message information. This is one of the Network Type Constants described in Chapter 71, "Telephony Network."

If this value is kTelNwkCDMA, then the advancedParams union contains a TelSmsDeliveryAdvancedCDMAType structure, and similarly for the other values.

advancedParams
Advanced message information for GSM, CDMA, or TDMA messages. This is one of the following structure types:

TelSmsDeliveryAdvancedGSMType 
TelSmsDeliveryAdvancedCDMAType 
TelSmsDeliveryAdvancedTDMAType 

<->
extensionsCount
On input, this is the number of extension structures allocated for this message. You must allocate at least one structure to specify the multipart information.

Upon return, this is the number of extensions in the SMS header. If the SMS header contains more extensions than you have allocated, the available extension structures are filled, and this function generates a telErrBufferSize error.
<->
extensionsP
A pointer to an array of TelSmsExtensionType structures that you have allocated for this message. You must allocate this array before using this structure.

New TelSmsExtensionType

The TelSmsExtensionType structure specifies multipart information about a message.

typedef struct _TelSmsExtensionType 
  UInt8    extensionTypeId; 
  union 
  { 
    TelSmsMultiPartExtensionType    mp; 
    TelSmsNbsExtensionType          nbs; 
    TelSmsUserExtensionType         user; 
  } extension; 
} TelSmsExtensionType; 

Field Descriptions

<->
extensionTypeId
Identifies the type of SMS extension structure found in the extension union. This is one of the SMS Extension Type Constants.

If the value of this field is kTelSmsMultipartExtensionTypeId, then the extension union contains a TelSmsMultiPartExtensionType structure.

If the value of this field is kTelSmsNbsExtensionTypeId or kTelSmsNbs2ExtensionTypeId, then the union contains a TelSmsNbsExtensionType structure. The difference between these two is that kTelSmsNbs2ExtensionTypeId indicates that the port value is a long instead of a short.

If this field contains any other value, then the union contains a TelSmsUserExtensionType structure.
<-
extension
The extension information, which is one of the following structure types:

TelSmsMultiPartExtensionType 
TelSmsNbsExtensionType 
TelSmsUserExtensionType 

New TelSmsGetAvailableStorageType

The TelSmsGetAvailableStorage function uses a TelSmsGetAvailableStorageType structure to retrieve information about the storage available on the phone.

typedef struct _TelSmsGetAvailableStorageType 
  UInt16   count; 
  UInt8    *storagesP; 
} TelSmsGetAvailableStorageType; 

Field Descriptions

<->
count
The size of the storagesP buffer.

When the structure is used as an input parameter, this is the allocated number of values in the buffer. Upon return, this is the total number of storage areas in the phone.
<-
storagesP
A buffer into which the retrieved storage IDs are stored. Each value stored into the buffer is one of the SMS Storage ID Constants.

New TelSmsGetMessageCountType

The TelSmsGetMessageCount function uses a TelSmsGetMessageCountType structure to retrieve information about messages in the currently selected storage.

typedef struct _TelSmsGetMessageCountType 
{ 
  UInt8    messageType; 
  UInt16   slots; 
  UInt16   count; 
} TelSmsGetMessageCountType; 

Field Descriptions

->
messageType
The type of message for which you want to retrieve the count. This must be one of the SMS Message Type Constants.

You must fill this in on input to the TelSmsGetMessageCount function.
<-
slots
The total number of message slots available in the currently selected storage area (for all message types).
<-
count
The number of filled slots for the specified messageType in the currently selected storage area.

New TelSmsManualAckType

The TelSmsSendManualAcknowledge function uses a TelSmsManualAckType structure to specify the information used to send a message acknowledgment.

typedef struct _TelSmsManualAckType 
{ 
  UInt16     version; 
  Char       *destinationAddress; 
  UInt32     messageId; 
  UInt16     dataSize; 
  UInt8      *data; 
  UInt8      dataCodingScheme; 
  UInt8      responseCode; 
} TelSmsManualAckType; 

Field Descriptions


version
The version of the SMS API used for this acknowledgment.

destinationAddress
The destination address. For GSM, the length of this address is 12 bytes. For CDMA, the length is up to 128 bytes.

messageId
Upon return, the ID of the acknowledgment.

dataSize
The size of the data buffer.

When the structure is used as an input parameter, this is the allocated size of the data buffer.

Upon return, this is the actual size of the data. If the buffer is too small to contain all of the data, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error.

data
A buffer into which the retrieved data is stored.

Note that if this buffer is too small to contain the all of the retrieved data, the data is truncated and the function using this structure generates a telErrBufferSize error.

dataCodingScheme
The coding scheme used for the data. This must be one of the SMS Data Coding Scheme Constants.

responseCode
The response code. The value of this field depends on the network being used.

New TelSmsMultiPartExtensionType

The TelSmsExtensionType structure uses a TelSmsMultiPartExtensionType structure to describe information about a multipart message.

typedef struct _TelSmsMultiPartExtensionType 
  UInt16  bytesSent; 
  UInt16  partCurrent; 
  UInt16  partCount; 
  UInt16  partId; 
} TelSmsMultiPartExtensionType; 

Field Descriptions

<->
bytesSent
On input, set this value to 0.

Upon return, this is the current count of message bytes that have been sent.

<->
partCurrent
On input, set this value to 0.

Upon return, this is the part number of the current message part.
<->
partCount
On input, set this value to 0.

Upon return, this is the number of message parts required to send the data.
<->
partId
The ID of the current SMS message. This ID is unique and is the same for all parts of the message. This information is required to reassemble a multi-part SMS.

On input, set this value to 0.

New TelSmsNbsExtensionType

The TelSmsExtensionType structure uses a TelSmsNbsExtensionType structure to describe information about a NBS message.

typedef struct _TelSmsNbsExtensionType 
  UInt16  destPort; 
  UInt16  srcPort; 
} TelSmsNbsExtensionType; 

Field Descriptions

<->
destPort
When the structure is used for input, this is the NBS port number used to encode the data.

Upon return, this is the NBS port number that was used for the data.
<->
srcPort
This is currently the same as the destPort.

New TelSmsReadMessagesType

The TelSmsReadMessages function uses a TelSmsReadMessagesType structure to retrieve messages from the currently selected storage area.

typedef struct _TelSmsReadMessagesType 
  UInt16                      first; 
  UInt16                      count; 
  TelSmsDeliveryMessageType  *messagesP; 
} TelSmsReadMessagesType; 

Field Descriptions

->
first
The index of the first message to retrieve. Message indexes are zero-based.
<->
count
The size of the messagesP buffer.

When the structure is used as an input parameter, this is the allocated number of pointers in the messagesP buffer.

Upon return, this is the number of messages that could be retrieved. If the messagesP buffer is too small to contain all of the messages, this field is assigned the entire count, and the function using this structure generates a telErrBufferSize error.
<->
messagesP
An array of pointers to TelSmsDeliveryMessageType structures, each of which is filled in with a retrieved message, if available.

New TelSmsReadReportsType

The TelSmsReadReports function uses a TelSmsReadReportsType structure to retrieve reports from the currently selected storage area.

typedef struct _TelSmsReadReportsType 
  UInt16             first; 
  UInt16             count; 
  TelSmsReportType   *reportsP; 
} TelSmsReadReportsType; 

Field Descriptions

->
first
The index of the first report to retrieve. Report indexes are zero-based.
<->
count
The size of the reportsP buffer.

When the structure is used as an input parameter, this is the allocated number of pointers in the reportsP buffer.

Upon return, this is the actual number of reports that could be read. If the buffer is too small to contain all of the reports, this field is assigned the entire count, and the function using this structure generates a telErrBufferSize error.
<->
reportsP
An array of pointers to TelSmsReportType structures, each of which is filled in with a retrieved message, if available.

Note that if this buffer is too small to contain all of the retrieved reports, the function using this structure generates a telErrBufferSize error.

New TelSmsReadSubmittedMessagesType

The TelSmsReadSubmittedMessages function uses a TelSmsReadSubmittedMessagesType structure to retrieve submitted messages from the currently selected storage area.

typedef struct _TelSmsReadMessagesType 
  UInt16                      first; 
  UInt16                      count; 
  TelSmsDeliveryMessageType  *submittedsP; 
} TelSmsReadSubmittedMessagesType; 

Field Descriptions

->
first
The index of the first message to retrieve. Message indexes are zero-based.
<->
count
The size of the submittedsP buffer.

When the structure is used as an input parameter, this is the allocated number of pointers in the submittedsP buffer. Upon return, this is the number of messages that were actually read.
<->
submittedsP
An array of pointers to TelSmsSubmittedMessageType structures, each of which is filled in with a retrieved message, if available.

New TelSmsReportType

The TelSmsReadReport function uses a TelSmsReportType structure to retrieve a report from the report storage area.

typedef struct _TelSmsReportType 
{ 
  UInt16               version; 
  UInt16               index; 
  UInt8                reportType; 
  UInt32               messageId; 
  UInt16               dataSize; 
  UInt8                *data; 
  UInt8                dataCodingScheme; 
  Char                 *originatingAddress; 
  UInt8                originatingAddressSize; 
  UInt8                report; 
  TelSmsDateTimeType   timeStamp; 
} TelSmsReportType; 

Field Descriptions

->
version

<-
index
The index of the report in the phone storage area.
<-
reportType
The delivery report type.
<-
messageId
The message ID.
<->
dataSize
The size of the data buffer.

When the structure is used as an input parameter, this is the allocated size of the data buffer.

Upon return, this is the actual size of the data. If the buffer is too small to contain all of the data, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error.
<->
data
A buffer into which the retrieved data is stored.

Note that if this buffer is too small to contain the all of the retrieved data, the data is truncated and the function using this structure generates a telErrBufferSize error.
<-
dataCodingScheme
The encoding scheme used for the report data. This must be one of the SMS Data Coding Scheme Constants.
<->
originatingAddress
A buffer into which the originating address is stored.

Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBuffrSize error.
<->
originatingAddressSize
The size of the originatingAddress buffer.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.
<-
report
The ID of the delivery confirmation report associated with the message.
<-
timeStamp
An TelSmsDateTimeType structure that stores the time at which the message corresponding to the report was received.

New TelSmsSendMessageType

typedef struct _TelSmsSendMessageType 
{ 
  UInt32                   messageId; 
  TelSmsSubmitMessageType  message; 
} TelSmsSendMessageType; 

Field Descriptions

<-
messageId
The SMS ID that was assigned by the telephone to the outgoing message.

For a multi-part message, each part has its own message ID.
->
message
A structure of type TelSmsSubmitMessageType that contains the message data and parameters.

New TelSmsSubmitAdvancedCDMAType

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedCDMAType structure for CDMA messages.

typedef struct _TelSmsSubmitAdvancedCDMAType 
{ 
  Boolean              manualAckRequest; 
  UInt8                messageType; 
  TelSmsDateTimeType   deferredDate; 
  UInt8                priority; 
  UInt8                privacy;	 
  Boolean              alertOnDeliveryRequest; 
  Char                 *callbackNumber;  
  UInt8                callbackNumberSize; 
} TelSmsSubmitAdvancedCDMAType; 

Field Descriptions


manualAckRequest
true if a reply is requested from the user, and false if not.

messageType
The type of the message. This must be one of the SMS Message Type Constants.

deferredDate


priority


privacy
The privacy type of the message. This must be one of the SMS Message Privacy Constants.

alertOnDeliveryRequest
true if the user is to be alerted upon delivery of this message, and false if not.

callbackNumber
A buffer into which the retrieved callback telephone number string is stored.

Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error.

callbackNumberSize
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumber string.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.

New TelSmsSubmitAdvancedGSMType

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedGSMType structure for GSM messages.

typedef struct _TelSmsSubmitAdvancedGSMType 
{ 
  UInt16       protocolId; 
  Boolean      rejectDuplicatedRequest; 
  Boolean      replyPath; 
  Char         *serviceCenterNumber;	 
  UInt8        serviceCenterNumberSize; 
} TelSmsSubmitAdvancedGSMType; 

Field Descriptions

->
protocolId
Specifies gateway information for routing a message to another transport.

Some service centers provide a gateway between SMS and other transports such as mail and FAX. Service centers may reject messages with protocolId values that are reserved or unsupported.

The mobile device does not interpret reserved or unsupported values, but does store them as received.
->
rejectDuplicatedRequest
A Boolean value that specifies if the service center should accept a submit message for a submit message that is still held in the service center when that message has the same identifier and destination address as a previously submitted message from the same originating address.
->
replyPath
The path that the service center can use to deliver a reply to the originating message.

The reply path is requested by the originating mobile device by setting the replyPath parameter in the original submit message.

If the service center supports reply path requests from the mobile device, the service center sets the replyPath parameter in the response.
->
serviceCenterNumber
A buffer containing the service telephone number string.
->
serviceCenterNumberSize
The allocated size, in bytes, of the serviceCenterNumber string.

New TelSmsSubmitAdvancedTDMAType

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedTDMAType structure for TDMA messages.

typedef struct _TelSmsSubmitAdvancedTDMAType 
{ 
  Boolean              manualAckRequest; 
  UInt8                messageType; 
  TelSmsDateTimeType   deferredDate; 
  UInt8                priority; 
  UInt8                privacy; 
  Boolean              alertOnDeliveryRequest; 
  Char                 *callbackNumber;  
  UInt8                callbackNumberSize; 
} TelSmsSubmitAdvancedTDMAType; 

Field Descriptions


manualAckRequest
true if a reply is requested from the user, and false if not.

messageType
The type of the message. This must be one of the SMS Message Type Constants.

deferredDate


priority


privacy
The privacy type of the message. This must be one of the SMS Message Privacy Constants.

alertOnDeliveryRequest
true if the user is to be alerted upon delivery of this message, and false if not.

callbackNumber
A buffer into which the retrieved callback telephone number string is stored.

Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error.

callbackNumberSize
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumber string.

Upon return, this is the actual size of the string, including the null terminator character. If the 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.

New TelSmsSubmitMessageType

The TelSmsReadReports and TelSmsSendMessageType structures use a TelSmsSubmitMessageType structure to stored reports retrieved from the currently selected storage area.

typedef struct _TelSmsSubmitMessageType 
{ 
  UInt16               version; 
  Boolean              networkDeliveryRequest; 
  Char                 *destinationAddress; 
  UInt8                destinationAddressSize; 
  UInt16               dataSize; 
  UInt8                *data; 
  UInt8                dataCodingScheme; 
  TelSmsDateTimeType   validityPeriod; 
  UInt8                standardType; 
  union 
  { 
    TelSmsSubmitAdvancedGSMType   advancedGSM; 
    TelSmsSubmitAdvancedCDMAType  advancedCDMA; 
    TelSmsSubmitAdvancedTDMAType  advancedTDMA; 
  } advancedParams; 
  UInt8                  extensionsCount; 
  TelSmsExtensionType    *extensionsP; 
} TelSmsSubmitMessageType; 

Field Descriptions

->
version
The version of the SMS API associated with this message.
->
networkDeliveryRequest
If this value is true, the service center accepts the submit message.
<->
destinationAddress
A buffer that contains the phone number of the message recipient.
<->
destinationAddressSize
The size of the destination address string.
<->
dataSize
The size of the data buffer.
<->
data
A buffer into which the retrieved message data is stored.
->
dataCodingScheme
The coding scheme used for the data. This is one of the SMS Data Coding Scheme Constants.
->
validityPeriod
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid.
->
standardType
Indicates which field of the advancedParams union contains the message information. This must be one of the Network Type Constants described in Chapter 71, "Telephony Network."

If this value is kTelNwkCDMA, then the advancedParams union contains a TelSmsDeliveryAdvancedCDMAType structure, and similarly for the other values.
->
advancedParams
Advanced message information for GSM, CDMA, or TDMA messages. This is a pointer to one of the following structure types:

TelSmsSubmitAdvancedCDMAType 
TelSmsDeliveryAdvancedGSMType 
TelSmsDeliveryAdvancedTDMAType 

<->
extensionsCount
The number of extension structures allocated for this message. You must allocate at least one structure to specify the multipart information.
<->
extensionsP
A pointer to an array of TelSmsExtensionType structures that you have allocated for this message.

New TelSmsSubmittedMessageType

The TelSmsReadSubmittedMessage function uses a TelSmsSubmittedMessageType structure to retrieve reports from the currently selected storage area.

typedef struct _TelSmsSubmittedMessageType 
{ 
  UInt16                   index; 
  TelSmsSubmitMessageType  message; 
} TelSmsSubmittedMessageType; 

Field Descriptions

->
index
The index of the message on the phone.
<-
message
A TelSmsSubmitMessageType structure that represents the message.

New TelSmsUserExtensionType

The TelSmsExtensionType structure uses a TelSmsUserExtensionType structure to describe a user-defined extended message header.

typedef struct _TelSmsUserExtensionType 
  UInt8   *extHeader; 
  UInt8   extHeaderSize; 
} TelSmsUserExtensionType; 

Field Descriptions

<->
extHeader
On input, this field must be set to 0.

Upon return, this is a pointer to the user-defined header content.
<->
extHeaderSize
On input, this field must be set to 0.

Upon return, this is the size of the user-defined header content.

Telephony SMS Constants

This section describes the constants used with the SMS service set of the telephony API.

SMS Extension Type Constants

The SMS extension type constants describe the type of extension used to represent part of a message.

Constant
Value
Description
kTelSmsMultiPartExtensionTypeId
0x00
A multipart short message.
kTelSmsNbsExtensionTypeId
0x04
An NBS message with short port number value.
kTelSmsNbs2ExtensionTypeId
0x05
An NBS message with long port number value.
(any other value)

A user-defined extension type.

SMS Message Type Constants

The SMS message type constants describe the delivery type of a message.

Constant
Value
Description
kTelSmsMessageTypeDelivered
0
A delivered message.
kTelSmsMessageTypeReport
1
A report message.
kTelSmsMessageTypeSubmitted
2
A submitted message.
kTelSmsMessageTypeManualAck
3
A manual acknowledgement message.
kTelSmsMessageTypeAllTypes
4
All messages.

SMS Message Transport Protocol Constants

The SMS message transport protocol constants describe the protocol used to deliver a message.

Constant
Value
Description
ktelSmsDefaultProtocol
0
The default message transport protocol.
kTelSmsFaxProtocol
1
A FAX message.
kTelSmsX400Protocol
2
An X.400 message.
kTelSmsPagingProtocol
3
A paged message.
kTelSmsEmailProtocol
4
An email message.
kTelSmsErmesProtocol
5
An Ermes message.
kTelSmsVoiceProtocol
6
A voice message.

SMS Storage ID Constants

The SMS storage ID constants describe the storage location of a message.

Constant
Value
Description
kTelSmsStorageSIM
0
Stored in the SIM.
kTelSmsStoragePhone
1
Stored in the phone.
kTelSmsStorageAdaptor
2
Stored in the telephone adaptor.
kTelSmsStorageFirstOem
3
Storage managed by the OEM.

This constant specifies the first OEM storage area. You can specify additional OEM storage areas by incrementing this value. For example, to specify the third OEM storage area, use the following:

kTelSmsStorageFirstOem+2 

SMS Data Coding Scheme Constants

The SMS data coding scheme constants describe the encoding used for SMS data.

Constant
Value
Description
kTelSms8BitsEncoding
0
8-bit encoding.
kTelSmsBitsASCIIEncoding
1
ANSI X3.4 encoding.
kTelSmsIA5Encoding
2
CCITT T.50 encoding.
kTelSmsIS91Encoding
3
TIA/EIA/IS-91 section 3.7.1 encoding.
kTelSmsUCS2Encoding
4
UCS2 encoding; used with GSM only.
kTelSmsDefaultGSMEncoding
5
Default encoding for GSM only.

SMS Message Urgency Constants

The SMS message urgency constants describe the priority level of a message in a TelSmsDeliveryAdvancedCDMAType or TelSmsDeliveryAdvancedTDMAType structure.

Constant
Value
Description
kTelSmsUrgencyNormal
0
Normal urgency.
kTelSmsUrgencyUrgent
1
An urgent message.
kTelSmsUrgencyEmergency
2
An emergency message.

SMS Message Privacy Constants

The SMS message privacy constants describe the privacy type of a message in a CDMA or TDMA advanced parameters.

Constant
Value
Description
kTelSmsPrivacyNotRestricted
0
Privacy level 0.
kTelSmsPrivacyRestricted
1
Privacy level 1.
kTelSmsPrivacyConfidential
2
Privacy level 2.
kTelSmsPrivacySecret
3
Privacy level 3.

Telephony SMS Functions

This section describes the functions used with the SMS service set of the telephony API.

New TelSmsDeleteMessage

Purpose

Delete an SMS report, delivered message, or submitted message.

Prototype

Err TelSmsDeleteMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsDeleteMessageType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsDeleteMessageType structure that specifies the index and type of the message to delete.
<-> 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 TelSmsDeleteMessageType structure passed to this function in the iDelInfoP parameter.
functionId
kTelSmsDeleteMessageMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Comments

If the deleted message has been delivered, the deletion is performed in the current storage, which you can set with the TelSmsSelectStorage function.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsGetAvailableStorage

Purpose

Retrieve the list of all available storage on the phone.

Prototype

Err TelSmsGetAvailableStorage(UInt16 iRefnum, TelAppID iAppId, TelSmsGetAvailableStorageType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsGetAvailableStorageType structure that is filled in with information about the storage areas available on 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 TelSmsGetAvailableStorageType structure passed to this function in the ioParamP parameter.
functionId
kTelSmsGetAvailableStorageMessage

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 count of storage areas available on the phone is stored into the count field of the TelSmsGetAvailableStorageType structure referenced by ioParamP, and the storage ID of each available room is stored into the buffer referenced by the storagesP field. If the storagesP buffer is too small to contain all of the storage IDs, the buffer is truncated and this function returns the telErrBufferSize error. The count field of the structure is always updated to contain the total number of available storage areas on the phone.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsGetDataMaxSize

Purpose

Returns the maximum length, in bytes, of a message on the current network.

Prototype

Err TelSmsGetDataMaxSize(UInt16 iRefnum, TelAppID iAppId, UInt16 *oSizeP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oSizePA pointer to an unsigned integer value that is updated witht he maximum length of an SMS message on the current network.
<-> 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 oSizeP parameter.
functionId
kTelGetDataMaxSizeMessage

WARNING! When using this function asynchronously, you must ensure that the value referenced by oSizeP remains in memory until the asynchronous call completes.

Comments

You can use this function to determine the maximum size you need to allocate to read a message.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsReadMessage, TelSmsReadMessages

New TelSmsGetMessageCount

Purpose

Retrieve the total number of message slots, and the number of filled slots for the specified message type.

Prototype

Err TelSmsGetMessageCount(UInt16 iRefnum, TelAppID iAppId, TelSmsGetMessageCountType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsGetMessageCountType structure that specifies the message type and is filled in with the count information.
<-> 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 TelSmsGetMessageCountType structure passed to this function in the ioParamP parameter.
functionId
kTelSmsGetMessageCountMessage

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 currently selected storage area pertains only to delivered messages; other message types are stored on the phone, but not in a specific storage area. If you specify delivered messages, this function retrieves information about the messages in the currently selected SMS storage area on the phone. If you specify a different message type, this function retrieves information about the messages in the phone.

You specify the message type by assigning one of the SMS Message Type Constants to the messageType field of the TelSmsGetMessageCountType structure before calling this function.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsGetSelectedStorage

Purpose

Retrieve the ID of the currently selected storage area on the phone.

Prototype

Err TelSmsGetSelectedStorage(UInt16 iRefnum, TelAppID iAppId, UInt8 *oStorageIdP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oStorageIdPA pointer to an unsigned byte value that is assigned the ID of the currently selected storage area on the phone. The assigned ID value is one of the SMS Storage ID 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 oStorageIdP parameter.
functionId
kTelGetSelectedStorageMessage

WARNING! When using this function asynchronously, you must ensure that the value referenced by oStorageIdP remains in memory until the asynchronous call completes.

Comments

The currently selected storage area pertains only to delivered messages; other message types are stored on the phone, but not in a specific storage area.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsGetUniquePartId

Purpose

Return a unique part identifier to assign to the partId field of a submit message.

Prototype

Err TelSmsGetUniquePartId(UInt16 iRefnum, TelAppID iAppId, UInt16 *oUniqueIdP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oUniqueIdPA pointer to a unsigned integer value. Upon return, this is the unique part ID value.
<-> 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 oUniqueIdP parameter.
functionId
kTelGetUniquePartIdMessage

WARNING! When using this function asynchronously, you must ensure that the value referenced by oUniquePartIdP remains in memory until the asynchronous call completes.

Comments

This function corresponds to the kTelUrqSmsGetUniquePartIdMessage value.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSendMessage

New TelSmsReadMessage

Purpose

Retrieve a delivered message from the currently selected storage area.

Prototype

Err TelSmsReadMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsDeliveryMessageType *ioMessageP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioMessagePA pointer to a TelSmsDeliveryMessageType structure that is filled in with the message.
On input, the index field of this structure contains the index of the message that you want retrieved. Message indexes are zero-based.
On input, the extensionsCount field specifies the number of extensions allocated in the extensionsP array. You must allocate at least one multi-part extension, even for a single-part message.
On input, the dataSize field specifies the allocated size of the data buffer, and the originatingAddressSize field specifies the allocated size of the originatingAddress string. Upon return, each size field specifies the complete size of the data that was stored into the buffer, even if the data had to be truncated to fit.
<-> 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 TelSmsDeliveryMessageType structure passed to this function in the ioMessageP parameter.
functionId
kTelSmsReadMessageMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioMessageP remains in memory until the asynchronous call completes.

Comments

The message data is stored into the data field of the TelSmsDeliveryMessageType structure referenced by ioMessageP. If the complete message data is too large to fit into the allocated size of the data field, the message data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the message data.

The originating address string is stored into the originatingData field of the TelSmsDeliveryMessageType structure referenced by ioMessageP. If the complete string is too large to fit into the allocated size of the originatingData field, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The originatingAddressSize field of the structure is always updated to contain the actual size of the string.

Before calling this function, you need to allocate a number of fields and structures in and related to the TelSmsDeliveryMessage structure:

Allocate each address field with a size of at least kTelMaxPhoneNumberLen + 1.

For example, for a GSM message, you must allocate the originatingAddress and serviceCenterNumber fields in the TelSmsDeliveryAdvancedGSMType structure in the TelSmsDeliveryMessage structure.

Allocate the message field data to have the maximum size of a message on the current network. You can determine this value by calling the TelSmsGetDataMaxSize function.

Allocate at least one TelSmsExtensionType structure in the TelSmsDeliveryMessage structure. You must have at least one extension structure, even if your message has only a single part. If you do not allocate enough extensions for the message, TelSmsReadMessage returns an error. Palm recommends allocating between 3 and 5 extensions for a message.

You should not allocate a pointer for user extension data. If you receive user extension data, the user extension pointer will reference a block in the message data. Do not deallocate the user extension data when you release the structure.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsReadMessages

Purpose

Retrieve a range of delivered messages from the currently selected storage area.

Prototype

Err TelSmsReadMessages(UInt16 iRefnum, TelAppID iAppId, TelSmsReadMessagesType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsReadMessagesType structure.
On input, the first field of this structure specifies the index of the first message to retrieve. Message indexes are zero-based.
On input the count field of this structure specifies the allocated size of the messagesP buffer. Upon return, the count field specifies the actual number of messages that were available, even if that many could not fit into the buffer.
The messagesP buffer must contain pointers to TelSmsDeliveryMessageType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadMessage function.
<-> 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 TelSmsReadMessagesType structure passed to this function in the ioParamP parameter.
functionId
kTelSmsReadMessagesMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP and all of the structures referenced by it remain in memory until the asynchronous call completes.

Comments

If the message data or originating address string data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the data is truncated into the buffer, and this function returns the telErrBufferSize error.

For more information about using this function and allocating structures for its use, see the Comments description for the TelSmsReadMessage function.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage

New TelSmsReadReport

Purpose

Read a report from the currently selected storage area.

Prototype

Err TelSmsReadReport(UInt16 iRefnum, TelAppID iAppId, TelSmsReportType *ioReportP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioReportPA pointer to a TelSmsReportType structure.
On input the index field of this structure contains the index of the message that you want retrieved. Message indexes are zero-based.
On input, the dataSize field specifies the allocated size of the data buffer, and the originatingAddressSize field specifies the allocated size of the originatingAddress string. Upon return, each size field specifies the complete size of the data that was stored into the buffer, even the data had to be truncated to fit.
<-> 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 TelSmsReportType structure passed to this function in the ioReportP parameter.
functionId
kTelSmsReadReportMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by iEntryP remains in memory until the asynchronous call completes.

Comments

The report data is stored into the data field of the TelSmsReportType structure referenced by ioReportP. If the complete message data is too large to fit into the allocated size of the data field, the report data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the report data.

The originating address string is stored into the originatingData field of the TelSmsReportType structure referenced by ioReportP. If the complete string is too large to fit into the allocated size of the originatingData field, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The originatingAddressSize field of the structure is always updated to contain the actual size of the string.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage, TelSmsSendMessage

New TelSmsReadReports

Purpose

Retrieve a range of reports from the currently selected storage.

Prototype

Err TelSmsReadReports(UInt16 iRefnum, TelAppID iAppId, TelSmsReadReportsType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsReadReportsType structure.
On input, the first field of this structure specifies the index of the first report to retrieve. Report indexes are zero-based.
On input the count field of this structure specifies the allocated size of the reportsP buffer. Upon return, the count field specifies the actual number of reports that were available, even if that many could not fit into the buffer.
The reportsP buffer must contain pointers to TelSmsReportType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadReport function.
<-> 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 TelSmsReadReportsType structure passed to this function in the ioParamP parameter.
functionId
kTelSmsReadReportsMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP and all of the structured referenced by it remain in memory until the asynchronous call completes.

Comments

If the report data or originating address string data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the data is truncated into the buffer, and this function returns the telErrBufferSize error. For more information, see the Comments description for the TelSmsReadReport function.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage, TelSmsSendMessage

New TelSmsReadSubmittedMessage

Purpose

Read a previously submitted message that was kept on the phone after being sent.

Prototype

Err TelSmsReadSubmittedMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsSubmittedMessageType *ioMessageP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioMessagePA pointer to a TelSmsSubmitMessageType structure that is filled in with the message.
On input, the index field contains the index of the message that you want retrieved. Message indexes are zero-based.
Upon return, the message field structure is filled in with the message information. You must initialize the buffer size fields of this structure prior to calling this function, including the dataSize, callbackNumberSize, serviceCenterNumberSize, and destinationAddressSize fields. Each of these fields is initialized with the allocated size of its corresponding buffer.
<-> 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 TelSmsSubmitMessageType structure passed to this function in the ioMessageP parameter.
functionId
kTelSmsSubmittedMessageMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by iEntryP remains in memory until the asynchronous call completes.

Comments

The message data is stored into the data field of the TelSmsSubmitMessageType structure referenced by ioMessageP. If the complete message data is too large to fit into the allocated size of the data field, the end of the message data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the message data.

The same strategy applies to the callbackNumber buffer and callbackNumberSize fields, the destinationAddress buffer and destinationAddressSize fields, and the serviceCenterNumber buffer and serviceCenterNumberSize fields. If the size of the data for any of the buffer fields exceeds the allocated length of the buffer, the end of the data is truncated and this function returns the telErrBufferSize error. Each of the size fields is always updated to contain the complete size of the data intended for the buffer.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage, TelSmsSendMessage

New TelSmsReadSubmittedMessages

Purpose

Retrieve a range of submitted messages from the currently selected storage area.

Prototype

Err TelSmsReadSubmittedMessages(UInt16 iRefnum, TelAppID iAppId, TelSmsReadSubmittedMessagesType *ioParamP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelSmsReadMessagesType structure.
On input, the first field of this structure specifies the index of the first message to retrieve. Message indexes are zero-based.
On input, the count field of this structure specifies the allocated size of the submittedsP buffer. Upon return, the count field specifies the actual number of messages that were available, even if that many could not fit into the buffer.
The submittedsP buffer must contain pointers to TelSmsSubmittedMessageType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadSubmittedMessage function.
<-> 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 TelSmsReadSubmittedMessagesType structure passed to this function in the ioParamP parameter.
functionId
kTelSmsReadSubmittedMessagesMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP and all of the structured referenced by it remain in memory until the asynchronous call completes.

Comments

If the message data or any of the other variable-length data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the end of the data is truncated, and this function returns the telErrBufferSize error. For more information, see the Comments description for the TelSmsReadSubmittedMessage function.

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage, TelSmsSendMessage

New TelSmsSelectStorage

Purpose

Select a storage area on the phone as the current storage area.

Prototype

Err TelSmsSelectStorage(UInt16 iRefnum, TelAppID iAppId, UInt8 iStorageId, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> ioStorageIdThe ID of the storage area. This must be one of the SMS Storage ID 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 ioStorageId parameter.
functionId
kTelSmsSelectStorageMessage

Comments

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsGetAvailableStorage, TelSmsGetSelectedStorage

New TelSmsSendManualAcknowledge

Purpose

Send a manual acknowledgment of a previously received message. Note that this function is not supported on GSM networks.

Prototype

Err TelSmsSendManualAcknowledge(UInt16 iRefnum, TelAppID iAppId, TelSmsManualAckType *ioAckP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioAckPA pointer to a structure of type TelSmsManualAckType. The fields of this structure specify information about the message being acknowledged.
Upon return, the messageId field is filled in with the ID of the acknowledgment.
<-> 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 TelSmsManualAckType structure passed to this function in the ioAckP parameter.
functionId
kTelSmsSendManualAcknowledgeMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by iEntryP remains in memory until the asynchronous call completes.

Comments

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

New TelSmsSendMessage

Purpose

Send an SMS message.

Prototype

Err TelSmsSendMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsSendMessageType *ioMessageP, UInt16 *ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioMessagePA pointer to a structure of type TelSmsSendMessageType.
On input, the message field of this structure contains a TelSmsSubmitMessageType with the message to send. You must also allocate and zero at least one TelSmsExtensionType structure for the multi-part information.
On output, the messageId field of this structure is filled in with the ID that was assigned to the sent message.
<-> 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 TelSmsSendMessageType structure passed to this function in the ioMessageP parameter.
functionId
kTelSmsSendMessageMessage

WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioMessageP remains in memory until the asynchronous call completes.

Comments

You need to make multiple calls to the TelSmsSendMessage function to send your message:

The first call to TelSmsSendMessage does not actually send the message. It computes the number of parts and fills in the multi-part extension structures in the TelSmsSendMessageType structure. Note that you must allocate at least one extension structure, even for single-part messages.

Subsequent calls to TelSmsSendMessage actually send the data.

To send an entire message, you need to call TelSmsSendMessage in a loop. Terminate the loop when an error occurs, or when the byteSend field of the first TelSmsExtensionType structure has the same value as the dataSize field of the TelSmsSendMessageType structure that represents the message. For example:


while (!TelSmsSendMessage(...) && 
        msg.extensionP[0].extension.mp.byteSend != dataSend); 

Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSmsSelectStorage, TelCfgSetSmsCenter