SMS Exchange Library
 

 < 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
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
Returns the default values for the SMS Exchange Library preferences.
exgLibSmsPrefSetOp
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.