< 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A pointer to a TelSmsDeleteMessageType structure that specifies the index and type of the message to delete.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A pointer to a TelSmsGetAvailableStorageType structure that is filled in with information about the storage areas available on 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<- oSizeP | A pointer to an unsigned integer value that is updated witht he maximum length of an SMS message on the current 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.
#### 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A pointer to a TelSmsGetMessageCountType structure that specifies the message type and is filled in with the count information.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<- oStorageIdP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<- oUniqueIdP | A pointer to a unsigned integer value. Upon return, this is the unique part ID value.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioMessageP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioReportP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioMessageP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
-> ioStorageId | The ID of the storage area. This must be one of the SMS Storage ID 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioAckP | A 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.
#####
<-> 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 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioMessageP | A 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.
#####
<-> 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 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 |