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

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

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.

85 SMS Exchange Library

SMS Exchange Library Data Structures ^TOP^

SmsParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsPrefType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsReceiveCDMAParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsReceiveGSMParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsReceiveParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsReceiveTDMAParamsType Typedef ^TOP^

Purpose

Prototype

Compatibility

SmsReportParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsSendCDMAParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsSendGSMParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SMSSendParamsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

SmsSendTDMAParamsType Typedef ^TOP^

Purpose

Prototype

Compatibility

SMS Exchange Library Constants ^TOP^

SMS Control Constants ^TOP^

Compatibility

SMS Data Coding Scheme Constants ^TOP^

Compatibility

SMS Network Type Constants ^TOP^

Compatibility

SMS Message Type Constants ^TOP^

Compatibility

SMS Converter Constants ^TOP^

Compatibility