(68K) Telephony SMS | Palm OS® Programmer's API Reference

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

This chapter describes:

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

Telephony SMS Data Structures ^TOP^

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

TelSmsDateTimeType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelSmsDateTimeType {
   Boolean absolute;
   UInt32 dateTime;
} TelSmsDateTimeType

Fields

→ absolute: If true, the dateTime value is an absolute time value specified as the number of seconds since 1/1/1904. This is the format returned by the TimGetSeconds() function. If false, the dateTime value is relative to the current date and time.
→ dateTime: The date and time value.

TelSmsDeleteMessageType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ 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.

TelSmsDeliveryAdvancedCDMAType Struct ^TOP^

Purpose

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedCDMAType structure for CDMA messages.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

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: The index of a new message in the in box.
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: Reserved.

TelSmsDeliveryAdvancedGSMType Struct ^TOP^

Purpose

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedGSMType structure for GSM messages.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

← 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.
↔ serviceCenterNumberSize: 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.

TelSmsDeliveryAdvancedTDMAType Struct ^TOP^

Purpose

The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedTDMAType structure for TDMA messages.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

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: The index of the message in the in box.
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.

TelSmsDeliveryMessageType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ 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 75, "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.

TelSmsExtensionType Struct ^TOP^

Purpose

The TelSmsExtensionType structure specifies multipart information about a message.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

↔ 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

TelSmsGetAvailableStorageType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

↔ 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.

TelSmsGetMessageCountType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ 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.

TelSmsManualAckType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

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.

TelSmsMultiPartExtensionType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

↔ 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.

TelSmsNbsExtensionType Struct ^TOP^

Purpose

The TelSmsExtensionType structure uses a TelSmsNbsExtensionType structure to describe information about a Narrow Band Sockets (NBS) message.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelSmsNbsExtensionType {
   UInt16 destPort, srcPort;
} TelSmsNbsExtensionType

Fields

↔ 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.

TelSmsReadMessagesType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ 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.

TelSmsReadReportsType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ 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.

TelSmsReadSubmittedMessagesType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelSmsReadSubmittedMessagesType {
   UInt16 first;
   UInt16 count;
   TelSmsSubmittedMessageType *submittedsP;
} TelSmsReadSubmittedMessagesType

Fields

→ 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.

TelSmsReportType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ version: The version of the SMS API. The current version number is kTelSmsAPIVersion.
← index: The index of the report in the phone storage area.
← reportType: The delivery report type. This is one of the SMS Report Types.
← 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 is 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. This is one of the SMS Delivery Status Reports constants.
← timeStamp: An TelSmsDateTimeType structure that stores the time at which the message corresponding to the report was received.

TelSmsSendMessageType Struct ^TOP^

Purpose

The TelSmsSendMessage() function uses this structure to send an SMS message.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

← 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.

TelSmsSubmitAdvancedCDMAType Struct ^TOP^

Purpose

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedCDMAType structure for CDMA messages.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

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: A date and time at which the message should be delivered. See TelSmsDateTimeType.
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.
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.

TelSmsSubmitAdvancedGSMType Struct ^TOP^

Purpose

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedGSMType structure for GSM messages.

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ protocolId: The protocol used for this message. This is one of the SMS Message Transport Protocol Constants.
→ 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: true if the next two parameters are set. false otherwise.
→ serviceCenterNumber: A buffer containing the SMS center number string. Replies to the originating message should go through this service center. Normally, you should set this to NULL.
→ serviceCenterNumberSize: The allocated size, in bytes, of the serviceCenterNumber string. Normally, the string is NULL and its size is 0.

TelSmsSubmitAdvancedTDMAType Typedef ^TOP^

Purpose

The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedTDMAType structure for TDMA messages.

Declared In

TelephonyMgrTypes.h

Prototype

typedef TelSmsSubmitAdvancedCDMAType 
TelSmsSubmitAdvancedTDMAType

TelSmsSubmitMessageType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ version: The version of the SMS API associated with this message. The constant kTelSmsAPIVersion gives the current version number.
→ networkDeliveryRequest: If this value is true, an acknowledgement is required.
↔ 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. Note that \0 is a meaningful character in the SMS character set and does not imply the end of the string.
→ 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 75, "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:; TelSmsSubmitAdvancedGSMType; TelSmsSubmitAdvancedCDMAType; TelSmsSubmitAdvancedTDMAType
↔ 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.

TelSmsSubmittedMessageType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

→ index: The index of the message on the phone.
← message: A TelSmsSubmitMessageType structure that represents the message.

TelSmsUserExtensionType Struct ^TOP^

Purpose

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

Declared In

TelephonyMgrTypes.h

Prototype

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

Fields

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

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

SMS Extension Type Constants ^TOP^

Purpose

The SMS extension type constants describe the type of extension used to represent part of a message. You can use one of the types listed here or define your own.

Declared In

TelephonyMgr.h

Constants

#define kTelSmsMultiPartExtensionTypeId 0x00: A multipart short message.
#define kTelSmsNbs2ExtensionTypeId 0x05: An NBS message with long port number value.
#define kTelSmsNbsExtensionTypeId 0x04: An NBS message with short port number value.

SMS Message Type Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

#define kTelSmsMessageTypeDelivered 0: A delivered message.
#define kTelSmsMessageTypeReport 1: A report message.
#define kTelSmsMessageTypeSubmitted 2: A submitted message.
#define kTelSmsMessageTypeManualAck 3: A manual acknowledgement message.
#define kTelSmsMessageAllTypes 4: All messages.

SMS Message Transport Protocol Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

Constants

#define kTelSmsDefaultProtocol 0: The default message transport protocol.
#define kTelSmsFaxProtocol 1: A FAX message.
#define kTelSmsX400Protocol 2: An X.400 message.
#define kTelSmsPagingProtocol 3: A paged message.
#define kTelSmsEmailProtocol 4: An email message.
#define kTelSmsErmesProtocol 5: An Ermes message.
#define kTelSmsVoiceProtocol 6: A voice message.

SMS Storage ID Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

Constants

#define kTelSmsStorageSIM 0: Stored in the SIM.
#define kTelSmsStoragePhone 1: Stored in the phone.
#define kTelSmsStorageAdaptor 2: Stored in the telephone adaptor.
#define 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 kTelSmsStorageFirstOem+2.

SMS Data Coding Scheme Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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

SMS Message Urgency Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

Constants

#define kTelSmsUrgencyNormal 0: Normal urgency.
#define kTelSmsUrgencyUrgent 1: An urgent message.
#define kTelSmsUrgencyEmergency 2: An emergency message.

SMS Message Privacy Constants ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

Constants

#define kTelSmsPrivacyNotRestricted 0: Privacy level 0.
#define kTelSmsPrivacyRestricted 1: Privacy level 1.
#define kTelSmsPrivacyConfidential 2: Privacy level 2.
#define kTelSmsPrivacySecret 3: Privacy level 3.

SMS Message Types ^TOP^

Purpose

Declared In

TelephonyMgr.h

Constants

#define kTelSmsCMTMessageType 0: Cellular Messaging Teleservice (CMT) message.
#define kTelSmsCPTMessageType 1: Cellular Paging Teleservice (CPT) message type.
#define kTelSmsVMNMessageType 2: Voice Mail Notification (VMN) message type.

SMS Delivery Status Reports ^TOP^

Purpose

Delivery status report codes used in the report field of the TelSmsReportType structure.

Declared In

TelephonyMgr.h

Constants

#define kTelSmsDSRSuccess 0: Success.
#define kTelSmsDSRMessageReplaced 1: Message replaced.
#define kTelSmsDSRMessageForwarded 2: Message forwarded.
#define kTelSmsDSRTempCongestion 3: Temporarily not delivered due to congestion.
#define kTelSmsDSRTempSMEBusy 4: Temporarily not delivered due to the mobile phone being busy.
#define kTelSmsDSRTempServiceRejected 5: Temporarily not delivered because the service rejected the message.
#define kTelSmsDSRTempServiceUnavailable 6: Temporarily not delivered due to the service being unavailable.
#define kTelSmsDSRTempSMEError 7: Temporarily not delivered due to an error in the mobile phone.
#define kTelSmsDSRTempOther 8: Temporarily not delivered due to some other cause.
#define kTelSmsDSRPermRPError 9: Delivery failed due to a reply path error.
#define kTelSmsDSRPermBadDestination 10: Delivery failed due to a bad destination address.
#define kTelSmsDSRPermUnobtainable 11: Delivery failed due to an error.
#define kTelSmsDSRPermServiceUnavailable 12: Delivery failed due to service unavailability.
#define kTelSmsDSRPermInternetworkError 13: Delivery failed due to an networking error.
#define kTelSmsDSRPermValidityExpired 14: Delivery failed due to its validity expiring.
#define kTelSmsDSRPermDeletedByOrigSME 15: Delivery failed due to the message being deleted by the originating mobile phone.
#define kTelSmsDSRPermDeleteByAdm 16: Delivery failed due to the message being deleted.
#define kTelSmsDSRPermSMNotExist 17: Delivery failed.
#define kTelSmsDSRPermOther 18: Delivery failed due to some other cause.

SMS Report Types ^TOP^

Purpose

Report types used in the reportType field of the TelSmsReportType structure.

Declared In

TelephonyMgr.h

Constants

#define kTelSmsStatusReportDeliveryType 0: Status report or delivery acknowledgement.
#define kTelSmsManualAckDeliveryType 1: Manual delivery acknowledgement.

Telephony SMS Functions ^TOP^

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

TelSmsDeleteMessage Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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 ioParamP 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.

TelSmsGetAvailableStorage Function ^TOP^

Purpose

Retrieve the list of all available storage on the phone.

Declared In

TelephonyMgr.h

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.

TelSmsGetDataMaxSize Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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 with the 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: kTelSmsGetDataMaxSizeMessage

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.

TelSmsGetMessageCount Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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.

TelSmsGetSelectedStorage Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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: kTelSmsGetSelectedStorageMessage

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.

TelSmsGetUniquePartId Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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: kTelUrqSmsGetUniquePartIdMessage

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.

TelSmsReadMessage Function ^TOP^

Purpose

Retrieve a delivered message from the currently selected storage area.

Declared In

TelephonyMgr.h

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.

TelSmsReadMessages Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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.

TelSmsReadReport Function ^TOP^

Purpose

Read a report from the currently selected storage area.

Declared In

TelephonyMgr.h

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.

TelSmsReadReports Function ^TOP^

Purpose

Retrieve a range of reports from the currently selected storage.

Declared In

TelephonyMgr.h

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.

TelSmsReadSubmittedMessage Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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: kTelSmsReadSubmittedMessageMessage

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.

TelSmsReadSubmittedMessages Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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

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.

TelSmsSelectStorage Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

Prototype

Err TelSmsSelectStorage(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt8 ioStorageId,
   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.

TelSmsSendManualAcknowledge Function ^TOP^

Purpose

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

Declared In

TelephonyMgr.h

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.

TelSmsSendMessage Function ^TOP^

Purpose

Send an SMS message.

Declared In

TelephonyMgr.h

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.

77 Telephony SMS

Telephony SMS Data Structures ^TOP^

TelSmsDateTimeType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsDeleteMessageType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsDeliveryAdvancedCDMAType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsDeliveryAdvancedGSMType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsDeliveryAdvancedTDMAType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsDeliveryMessageType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsExtensionType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsGetAvailableStorageType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsGetMessageCountType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsManualAckType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsMultiPartExtensionType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsNbsExtensionType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsReadMessagesType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsReadReportsType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsReadSubmittedMessagesType Struct ^TOP^

Purpose

Declared In

Prototype

Fields

TelSmsReportType Struct ^TOP^

Purpose

Declared In