Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

85    SMS Exchange Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter describes the SMS Exchange Library API declared in the header file SmsLib.h. It discusses the following topics:

You interact with the SMS Exchange Library using the Exchange Manager APIs described in Chapter 62, "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 ^TOP^

SmsParamsType Struct ^TOP^

Purpose

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.

Prototype

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;

Fields

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 description of the appCreator field 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 description of the appCreator field 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.

SmsPrefType Struct ^TOP^

Purpose

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.

Prototype

typedef struct SmsPrefTag {
UInt32 validity;
UInt16 warnOver;
Boolean leave;
Boolean report;
Boolean autoSMSC;
Char smscNumber[kSmsMaxPhoneSize];
} SmsPrefType, *SmsPrefPtr;

Fields

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.

SmsReceiveCDMAParamsType Struct ^TOP^

Purpose

The SmsReceiveParamsType includes an SmsReceiveCDMAParamsType structure for CDMA messages.

Prototype

typedef struct SmsReceiveCDMAParamsTag {
UInt8 messageType;
TelSmsDateTimeType validityPeriod;
UInt8 priority;
UInt8 privacy;
Boolean alertOnDeliveryRequest;
Boolean manualAckRequest;
UInt8 voiceMessageNumber;
UInt8 languageIndicator;
Char *callbackNumberAddress; 
} SmsReceiveCDMAParamsType, 
*SmsReceiveCDMAParamsPtr;

Fields

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.

SmsReceiveGSMParamsType Struct ^TOP^

Purpose

The SmsReceiveParamsType includes an SmsReceiveGSMParamsType structure for GSM messages.

Prototype

typedef struct SmsReceiveGSMParamsTag {
UInt16 protocolId;
Char *serviceCenterNumber;
Boolean replyPath;
} SmsReceiveGSMParamsType, 
*SmsReceiveGSMParamsPtr;

Fields

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.

SmsReceiveParamsType Struct ^TOP^

Purpose

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.

Prototype

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;

Fields

timeStamp
The time at which the message was delivered, given as the number of seconds since January1, 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.

SmsReceiveTDMAParamsType Typedef ^TOP^

Purpose

The SmsReceiveParamsType includes an SmsReceiveTDMAParamsType structure for TDMA messages. This structure is currently the same as the SmsReceiveCDMAParamsType structure.

Prototype

typedef SmsReceiveCDMAParamsType 
SmsReceiveTDMAParamsType, 
*SmsReceiveTDMAParamsPtr;

Compatibility

This structure is only defined if 4.0 New Feature Set is present.

SmsReportParamsType Struct ^TOP^

Purpose

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.

Prototype

typedef struct SmsReportParamsTag {
UInt32 timeStamp;
UInt16 index;
UInt8 reportType;
UInt8 report;
Char *originatingAddress;
} SmsReportParamsType, *SmsReportParamsPtr;

Fields

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.

SmsSendCDMAParamsType Struct ^TOP^

Purpose

The SMSSendParamsType includes an SmsSendCDMAParamsType structure for CDMA messages.

Prototype

typedef struct SmsSendCDMAParamsTag {
UInt8 messageType;
TelSmsDateTimeType deferredDate;
UInt8 priority;
UInt8 privacy;
UInt8 alertOnDelivery:1;
UInt8 manualAckRequest:1;
UInt8 reserved:6;
Char *callbackNumber;
} SmsSendCDMAParamsType, *SmsSendCDMAParamsPtr;

Fields

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.

SmsSendGSMParamsType Struct ^TOP^

Purpose

The SMSSendParamsType includes an SmsSendGSMParamsType structure for GSM messages.

Prototype

typedef struct SmsSendGSMParamsTag {
UInt16 protocolId;
Char *serviceCenterNumber;
Boolean rejectDuplicated;
Boolean replyPath;
} SmsSendGSMParamsType, *SmsSendGSMParamsPtr;

Fields

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.

SMSSendParamsType Struct ^TOP^

Purpose

The SMSSendParamsType structure is used as the data field for the SmsParamsType structure when the SMS Exchange Library is sending data.

Prototype

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;

Fields

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.

SmsSendTDMAParamsType Typedef ^TOP^

Purpose

The SMSSendParamsType includes an SmsSendTDMAParamsType structure for TDMA messages. This structure is currently the same as the SmsSendCDMAParamsType structure.

Prototype

typedef SmsSendCDMAParamsType 
SmsSendTDMAParamsType, *SmsSendTDMAParamsPtr;

Compatibility

This structure is only defined if 4.0 New Feature Set is present.

SMS Exchange Library Constants ^TOP^

SMS Control Constants ^TOP^

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 85.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 ^TOP^

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

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

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

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.