< Home < Developers < Development Support < Documentation

## 77 SMS Exchange Library

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part IV: Libraries 77 SMS Exchange Library SMS Exchange Library Data Structures SmsParamsType SmsPrefType SmsReceiveCDMAParamsType SmsReceiveGSMParamsType SmsReceiveParamsType SmsReceiveTDMAParamsType SmsReportParamsType SmsSendCDMAParamsType SmsSendGSMParamsType SMSSendParamsType SmsSendTDMAParamsType SMS Exchange Library Constants SMS Control Constants SMS Data Coding Scheme Constants SMS Network Type Constants SMS Message Type Constants SMS Converter Constants |  |  |  | This chapter describes the SMS Exchange Library API declared in the header file SmsLib.h. It discusses the following topics: SMS Exchange Library Data Structures SMS Exchange Library Constants You interact with the SMS Exchange Library using the Exchange Manager APIs described in Chapter 58, "Exchange Manager," of this book. For further information on using Exchange Manager, see "Object Exchange" of the of the Palm OS Programmer's Companion, vol. II, Communications. ## SMS Exchange Library Data Structures ## New SmsParamsType The SmsParamsType structure identifies information specific to the SMS Exchange Library. The socketRef field of the ExgSocketType structure is set to this structure when you send or receive data using the SMS Exchange Library. You only need to create this structure and assign it to the socketRef field if you have an SMS message to send and want to use non-default values for some of the fields; otherwise, the SMS Exchange Library creates this structure for you and provides default values.
    typedef struct SmsParamsTag
    {
      UInt32 creator;
      UInt16 smsID;
      Char *extension;
      Char *mimeTypes;
      UInt32 appCreator;
      UInt8 dataCodingScheme;
      UInt8 networkType;
      UInt8 dataType;
      UInt16 nbsDestPort;
      UInt16 nbsSrcPort;
      union
      {
        SmsSendParamsType send;
        SmsReceiveParamsType receive;
        SmsReportParamsType report;

      } data;

    } SmsParamsType, *SmsParamsPtr;
#### Field Descriptions #####
creator | Creator ID of the SMS Exchange Library. Always set this to sysFileCSmsLib.
smsID | The ID of the message that was sent. Do not set this field directly; the SMS Exchange Library should set it.
extension | If the SMS message has an attachment, this field specifies the attachment name. Do not set this field directly; the SMS Exchange Library sets it if necessary. See the appCreator field description for details.
mimeTypes | If the SMS message has an attachment, this field specifies the MIME type of the attachment. Do not set this field directly; the SMS Exchange Library sets it if necessary. See the appCreator field description for details.
appCreator | The creator ID of the target application for the attachment to the SMS message. Do not set this field directly; the SMS Exchange Library sets it if necessary.
| When the SMS Exchange Library receives a message with an attachment, it unwraps the message and attempts to deliver the attachment directly to an application that is registered to receive it. If no application is registered to receive unwrapped attachments of that type, the SMS Exchange Library sends the entire SMS message, and it sets the extension, mimeTypes, and appCreator fields in this structure. The SMS application can use this information to have the Exchange Manager deliver the attachment to the appropriate application using the Local Exchange Library.
dataCodingScheme | The data encoding scheme that the message uses. See SMS Data Coding Scheme Constants.
networkType | Indicates the type of advanced parameters. See SMS Network Type Constants.
dataType | Identifies the type of message being received, such as multipart or return receipt. See SMS Message Type Constants.
nbsDestPort | The Narrow Band Socket (NBS) port on which you want the data sent. The SMS Exchange Library sets this for you if you leave it blank. When data is being received, this field is set to the NBS port on which the data was received.
nbsSrcPort | The NBS port on which you want the data sent. You should set this field to the same value as nbsDestPort. If you leave it blank, the SMS Exchange Library provides a value for you.
data | The data being sent or received. See SmsReceiveParamsType, SmsReportParamsType, and SMSSendParamsType.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsPrefType The SmsPrefType structure defines the SMS Exchange Library preferences for sending and receiving SMS messages. Applications can use the ExgControl function to get, set, or display these preferences to the user.
    typedef struct SmsPrefTag
    {
      UInt32 validity;
      UInt16 warnOver;
      Boolean leave;
      Boolean report;
      Boolean autoSMSC;
      Char smscNumber[kSmsMaxPhoneSize];
    } SmsPrefType, *SmsPrefPtr;
#### Field Descriptions #####
validity | The number of seconds before the message expires. If the message cannot be delivered to the recipient, the service center repeatedly attempts to deliver the message until it expires. The default is one hour.
warnOver | The number of parts a user can send without confirmation. If the user attempts to send a message with more than this number of parts, an alert is displayed, and the user can choose to send the message anyway. The default is 3 parts. (If the user attempts to send a message with more than 3 parts, an alert is displayed.)
leave | If true, any incoming messages retrieved from a phone remain on the phone as well. If false, the messages are deleted from the phone's inbox.
report | If true, the user receives confirmation that an SMS message was delivered.
autoSMSC | If true, don't use the value stored in the smscNumber field.
smscNumber | The message center to be used. If NULL or the empty string, the SMS message center set by the phone is used.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsReceiveCDMAParamsType The SmsReceiveParamsType includes an SmsReceiveCDMAParamsType structure for CDMA messages.
    typedef struct SmsReceiveCDMAParamsTag
    {
      UInt8 messageType;
      TelSmsDateTimeType validityPeriod;
      UInt8 priority;
      UInt8    privacy;
      Boolean alertOnDeliveryRequest;
      Boolean manualAckRequest;
      UInt8    voiceMessageNumber;
      UInt8    languageIndicator;
      Char *   callbackNumberAddress;
    } SmsReceiveCDMAParamsType, *SmsReceiveCDMAParamsPtr;
#### Field Descriptions
messageType | The type of the message. This is one of the SMS Message Type Constants constants defined in TelephonyMgr.h.
validityPeriod | The amount of time for which the message is valid. See TelSmsDateTimeType. The default is set according to the SMS preferences.
priority | The message priority. This must be one of the SMS Message Urgency Constants defined in TelephonyMgr.h.
privacy | The privacy type of the message. This must be one of the SMS Message Privacy Constants defined in TelephonyMgr.h.
alertOnDeliveryRequest | true if the user is to be alerted upon delivery of this message, and false if not.
manualAckRequest | true if a confirmation is requested from the recipient, and false if not.
voiceMessageNumber | The number of new messages in your voice mail.
languageIndicator | Reserved for future use.
callbackNumberAddress | The callback number to which confirmations are to be sent.
##### #### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsReceiveGSMParamsType The SmsReceiveParamsType includes an SmsReceiveGSMParamsType structure for GSM messages.
    typedef struct SmsReceiveGSMParamsTag
    {
      UInt16 protocolId;
      Char *serviceCenterNumber;
      Boolean replyPath;
    } SmsReceiveGSMParamsType, *SmsReceiveGSMParamsPtr;
#### Field Descriptions #####
protocolId | Reserved for future use.
serviceCenterNumber | The SMS service center that must be used to send a reply. If NULL, the service center specified in the preferences is used.
replyPath | If true, replies must be made through the SMS service center specified by serviceCenterNumber.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsReceiveParamsType The SmsReceiveParamsType structure is used as the data field for the SmsParamsType structure when the SMS Exchange Library has received data. The SMS Exchange Library always supplies the values for these fields.
    typedef struct SmsReceiveParamsTag
    {
      UInt32 timeStamp;
      Char *originatingAddress;
      UInt8 leaveOnPhone:1;
      UInt8 forceSlotMode:1;
      UInt8 reserved:6;
      UInt16 index;
      Boolean otherToReceive;
      Boolean reportDeliveryIndicator;
      union
      {
        SmsReceiveGSMParamsType gsm;
        SmsReceiveCDMAParamsType cdma;
        SmsReceiveTDMAParamsType tdma;
      } protocol;
    } SmsReceiveParamsType, *SmsReceiveParamsPtr;
#### Field Descriptions #####
timeStamp | The time at which the message was delivered, given as the number of seconds since January 1, 1904.
originatingAddress | The number from which the message was received.
leaveOnPhone | If true, messages received on the phone are not deleted from the phone's inbox. If not specified, this is set according to the system preferences.
forceSlotMode | If true, use slot mode parsing. If false, use block mode parsing. The default is block mode.
reserved | Reserved for future use.
index | Location where the message is stored on the mobile phone.
otherToReceive | If true, there are more messages to be received from the service center.
reportDeliveryIndicator | If true, the sender has requested confirmation. The recipient of the message does not send the confirmation; the SMS service center does.
protocol | Values specific to the protocol used to send the message. Currently, only GSM is supported.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsReceiveTDMAParamsType The SmsReceiveParamsType includes an SmsReceiveTDMAParamsType structure for TDMA messages. This structure is currently the same as the SmsReceiveCDMAParamsType structure.
    typedef SmsReceiveCDMAParamsType
      SmsReceiveTDMAParamsType,
      *SmsReceiveTDMAParamsPtr;
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsReportParamsType The SMSReportParamsType structure is used as the data field for the SmsParamsType structure when the SMS Exchange Library has received a delivery confirmation. The SMS Exchange Library always sets the values for these fields.
    typedef struct SmsReportParamsTag
    {
      UInt32 timeStamp;
      UInt16 index;
      UInt8 reportType;
      UInt8 report;
      Char* originatingAddress;
    } SmsReportParamsType, *SmsReportParamsPtr;
#### Field Descriptions #####
timeStamp | The date and time at which the message was delivered, given as the number of seconds since January 1, 1904.
index | Location where the message is stored on the mobile phone.
reportType | One of the Delivery Report Type constants defined in TelephonyMgr.h.
report | One of the Delivery Status Report constants defined in TelephonyMgr.h.
originatingAddress | Phone number to which the message was sent.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsSendCDMAParamsType The SMSSendParamsType includes an SmsSendCDMAParamsType structure for CDMA messages.
    typedef struct SmsSendCDMAParamsTag
    {
      UInt8   messageType;
      TelSmsDateTimeType deferredDate;
      UInt8   priority;
      UInt8   privacy;
      UInt8   alertOnDelivery:1;
      UInt8   manualAckRequest:1;
      UInt8   reserved:6;
      Char*   callbackNumber;
    } SmsSendCDMAParamsType, *SmsSendCDMAParamsPtr;
#### Field Descriptions #####
messageType | The type of the message. This is one of the SMS Message Type Constants constants defined in TelephonyMgr.h.
deferredDate | Not used.
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.
alertOnDelivery | true if the user is to be alerted upon delivery of this message, and false if not.
manualAckRequest | true if a confirmation is requested from the recipient, and false if not.
reserved | Reserved for future use.
callbackNumber | Number to which the confirmation should be sent.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsSendGSMParamsType The SMSSendParamsType includes an SmsSendGSMParamsType structure for GSM messages.
    typedef struct SmsSendGSMParamsTag
    {
      UInt16 protocolId;
      Char *serviceCenterNumber;
      Boolean rejectDuplicated;
      Boolean replyPath;
    } SmsSendGSMParamsType, *SmsSendGSMParamsPtr;
#### Field Descriptions #####
protocolId | Reserved for future use.
serviceCenterNumber | The message center to be used. If not specified, the service center is set according to the system preferences.
rejectDuplicated | If true, the service center rejects messages that have the same message ID, destination address, and originating address as a previously submitted message.
replyPath | If true, the service center that delivers the message is requested to provide information about itself to the recipient so that replies are made through the same service center.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SMSSendParamsType The SMSSendParamsType structure is used as the data field for the SmsParamsType structure when the SMS Exchange Library is sending data.
    typedef struct SmsSendParamsTag
    {
      TelSmsDateTimeType validityPeriod;
      Char *destinationAddress;
      UInt8 networkDeliveryRequested:1;
      UInt8 ignoreDefaultValue:1;
      UInt8 reserved:6;
      UInt16 partCount;
      UInt16 lastPart;
      UInt8 converter;
      union
      {
        SmsSendGSMParamsType gsm;
        SmsSendCDMAParamsType cdma;
        SmsSendTDMAParamsType tdma;
      } protocol;
    } SmsSendParamsType, *SmsSendParamsPtr;
#### Field Descriptions #####
validityPeriod | The amount of time for which the message is valid. See TelSmsDateTimeType. The default is set according to the SMS preferences.
destinationAddress | A buffer that contains the phone number of the message recipient. If no phone number is supplied, the user is prompted for the phone number.
networkDeliveryRequested | If true, the SMS service center sends a delivery confirmation. The default is set according to the SMS preferences. The SMS Exchange Library disables this field for multipart messages.
ignoreDefaultValue | If false, the validity period, network delivery requested, and SMS center specified in the preferences are used regardless of the values supplied in this structure. If true, the values supplied in this structure are used.
reserved | Reserved for future use.
partCount | The number of parts in the message. 0 means that the message is not a multipart message. If NBS is used to send the message, it determines the number of parts.
lastPart | The last part of a multipart message that was successfully sent.
converter | The header added to the data to specify how it is converted.
protocol | Data specific to the protocol used to send the message. Currently, only GSM is supported.
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## New SmsSendTDMAParamsType The SMSSendParamsType includes an SmsSendTDMAParamsType structure for TDMA messages. This structure is currently the same as the SmsSendCDMAParamsType structure.
    typedef SmsSendCDMAParamsType
      SmsSendTDMAParamsType,
      *SmsSendTDMAParamsPtr;
#### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## SMS Exchange Library Constants ## SMS Control Constants The SMS control constants are passed as the operation parameter to the ExgControl function. The ExgControl function is a way to communicate directly with the SMS Exchange Library. The following table lists the operation constant, the type of data that should be passed as the valueP parameter to ExgControl, and what the SMS Exchange Library does in response. #####
Table 77.1 ExgControl operations for SMS library
Operation | value Data Type | Description
--- | --- | ---
exgLibSmsPrefGetOp | SmsPrefType | Returns a pointer to the SMS Exchange Libraries preferences in valueP, creating the preferences and setting them to the default values if they do not exist.
exgLibSmsPrefGet DefaultOp | SmsPrefType | Returns the default values for the SMS Exchange Library preferences.
exgLibSmsPrefSetOp | SmsPrefType | Sets the SMS Exchange Library preferences to the values passed in valueP.
exgLibSmsPref DisplayOp | kSmsNetworkAuto or kSmsNetworkGSM. Input only. | Display a form that allows the user to set the SMS preferences.
exgLibSms IncompleteGetCountOp | UInt16. Output only. | Get the number of incomplete messages currently stored in the SMS Exchange Library. The library stores message parts as it receives them. When it has received all of the parts, it reassembles the message and delivers it. This operation tells how many messages are currently under assembly.
exgLibSms IncompleteDeleteOp | UInt16. Input only. | Delete the incomplete message with the ID passed in valueP. Pass -1 to delete all incomplete messages.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## SMS Data Coding Scheme Constants The SMS data coding scheme constants describe the coding scheme used for SMS data. These values are used as the dataCodingScheme parameter of the SmsParamsType structure. #####
Constant | Value | Description
--- | --- | ---
kSmsRowDataEncoding | 0 | 8-bit encoding scheme. This is the default.
kSmsTextEncoding | 1 | 7-bit encoding scheme.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## SMS Network Type Constants The SMS network type constants identify the type of network being used for SMS messages. Currently, only the GSM network is supported. #####
Constant | Value | Description
--- | --- | ---
kSmsNetworkAuto | -1 | The network is set by the phone. This is the default.
kSmsNetworkCDMA | kTelNwkCDMA | A CDMA network. Currently not supported.
kSmsNetworkGSM | kTelNwkGSM | A GSM network.
kSmsNetworkTDMA | kTelNwkTDMA | A TDMA network. Currently not supported.
kSmsNetworkPDC | kTelNwkPDC | A PDC network. Currently not supported.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## SMS Message Type Constants The SMS message type constants identify the type of message being sent. They are used as the dataType field of the SmsParamsType structure. #####
Constant | Value | Description
--- | --- | ---
kSmsMessageType | 0 | Standard SMS message of no more than 160 bytes. This is the default.
kSmsIncompleteType | 1 | A part of a multipart SMS message.
kSmsReportType | 2 | A confirmation, indicating that an SMS message was successfully sent.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## SMS Converter Constants The SMS converter constants identify the header information added to an SMS message. #####
Constant | Value | Description
--- | --- | ---
kSmsNBSConverter | 0 | An NBS header is added to the message. This is the default.
kSmsNoConverter | 1 | No header is added to the message.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. |