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 5, "Exchange Manager Reference," of the book Exploring Palm OS: High-Level Communications. For further information on using Exchange Manager, see Chapter 4, "Object Exchange," of the book Exploring Palm OS: High-Level Communications.
Note that the SMS Exchange Library does not implement the ExgGet()
function.
SMS Exchange Library Data Structures
SmsParamsType Struct
Purpose
Identifies information specific to the SMS Exchange Library.
Declared In
SmsLib.h
Prototype
typedef struct SmsParamsType { uint32_t creator; char *extension; char *mimeTypes; uint32_t appCreator; TelSmsMessageType message; uint16_t requestType; uint16_t storageId; Boolean leaveOnPhone; Boolean forceSlotMode; Boolean ignoreDefaultValue; uint8_t padding[1]; } SmsParamsType, *SmsParamsPtr
Fields
-
creator
- Creator ID of the SMS Exchange Library. Always set this to
sysFileCSmsLib
. -
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
, andappCreator
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. -
message
- A
TelSmsMessageType
structure holding the message that was sent. Do not set this field directly; the SMS Exchange Library should set it. -
requestType
- One of the constants described in "SMS Message Types." These constants can be ORed together.
-
storageId
- Used internally to retrieve a specific message.
-
leaveOnPhone
- Set this to
true
on input to leave received messages on the phone; set tofalse
(default) to delete messages from the phone once they are received. Received messages are stored in the SMS Messenger inbox. -
forceSlotMode
- Set this to
true
on input to force the parsing method to slot mode; set tofalse
to use block mode (default). In slot mode, SMS messages are read one at a time and in block mode, they are read all in one block. -
ignoreDefaultValue
- Set this to
true
on input to ignore the default values for validity period and SMS delivery request that are saved in the preferences; instead use the parameters in the structure. Set tofalse
to use the values in the preferences. -
padding
- Padding byte.
Comments
The socketRef
field of the ExgSocketType
structure is set to this structure when you send or receive data using the SMS Exchange Library. You need to create this structure and assign it to the socketRef
field only 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.
When receiving an SMS message, the application is sub-launched by the Exchange Manager using the sysAppLaunchCmdExgReceiveData
launch code. A flattened SMSParamsType
structure is defined in the ExgSocketType.socketRef
field and its size is in the ExgSocketType.socketRefSize
field. You must unflatten the SMSParamsType
structure before using it. This can be done with the code shown in the Example section.
Example
This example shows how to unflatten the SMSParamsType
structure when receiving an SMS message.
// Accept will open a progress dialog and wait for your receive commands err = ExgAccept(exgSocketP); if (err >= errNone) { // Get all application specific info, unflatten it first if ((err = PrvSmsExgUnflattenSmsParamsType((uint8_t*)exgSocketP->socketRef, (size_t) exgSocketP->socketRefSize, &smsParam)) != errNone) goto Exit; err = exgErrBadParam; messageType = kSmsMessageTypeIn; switch(smsParam.message.messageType) { case kTelSmsMessageTypeDelivered: if (smsParam.message.message.deliver.networkParams.gsm.messageClass == kTelSmsClass0) messageType = kSmsMessageTypeFlash; break; case kTelSmsMessageTypeReport: messageType = kSmsMessageTypeReport; break; } // your code continues here . . . } // The unflatten code should be: /****************************************************************************** * * Function: PrvSmsExgUnflattenSmsParamsType * * Description: Unflatten an input buffer into an SmsParamsType structure * * Parameters: * bufferP - input: pointer to a flat buffer. * bufferSize - input: the size of the flat buffer. * smsParamsP - output: pointer to a filled SmsParamsType structure. * * Returned: error if any. ******************************************************************************/ static status_t PrvSmsExgUnflattenSmsParamsType(uint8_t* bufferP, size_t bufferSize, SmsParamsType* smsParamsP ) { uint8_t* offsetP = bufferP; int32_t lenRemaining = bufferSize; // Initialize the structure memset(smsParamsP, 0, sizeof(SmsParamsType)); // Check the tag if (lenRemaining < (int32_t)sizeof(uint32_t)) { uint32_t value; memmove(&value, offsetP, sizeof(uint32_t)); if (value != sysFileCSmsLib) return exgErrBadParam; } offsetP += sizeof(uint32_t); lenRemaining -= sizeof(uint32_t); // Get the structure if (lenRemaining >= (int32_t)sizeof(SmsParamsType)) { memmove(smsParamsP, offsetP, sizeof(SmsParamsType)); } offsetP += sizeof(SmsParamsType); lenRemaining -= sizeof(SmsParamsType); // Get the address 1 if (smsParamsP->message.address1.size && (lenRemaining >= (int32_t)smsParamsP->message.address1.size)) { // Allocate address 1 memory if ((smsParamsP->message.address1.numberP = (char*)MemPtrNew(smsParamsP->message.address1.size)) == NULL) goto cleanup; memmove(smsParamsP->message.address1.numberP, offsetP, smsParamsP->message.address1.size); } offsetP += smsParamsP->message.address1.size; lenRemaining -= smsParamsP->message.address1.size; // Get the address 2 if (smsParamsP->message.address2.size && (lenRemaining >= (int32_t)smsParamsP->message.address2.size)) { // Allocate address 2 memory if ((smsParamsP->message.address2.numberP = (char*)MemPtrNew(smsParamsP->message.address2.size)) == NULL) goto cleanup; memmove(smsParamsP->message.address2.numberP, offsetP, smsParamsP->message.address2.size); } offsetP += smsParamsP->message.address2.size; lenRemaining -= smsParamsP->message.address2.size; // Get the extensions if (smsParamsP->message.extensionCount && (lenRemaining >= (int32_t) (sizeof(TelSmsExtensionType) * smsParamsP->message.extensionCount))) { // Allocate extensions memory if ((smsParamsP->message.extensionP = (TelSmsExtensionType*)MemPtrNew((size_t) (sizeof(TelSmsExtensionType) * smsParamsP->message.extensionCount))) == NULL) goto cleanup; memmove(smsParamsP->message.extensionP, offsetP, sizeof(TelSmsExtensionType) * smsParamsP->message.extensionCount); } offsetP += sizeof(TelSmsExtensionType) * smsParamsP->message.extensionCount; lenRemaining -= (int32_t)sizeof(TelSmsExtensionType) * smsParamsP->message.extensionCount; // Get the extension string if ( smsParamsP->extension && lenRemaining) { // Allocate extension string memory if ((smsParamsP->extension = (char*)MemPtrNew((size_t) (strlen((char*)offsetP) + 1))) == NULL) goto cleanup; memmove(smsParamsP->extension, offsetP, strlen((char*)offsetP) + 1); lenRemaining -= (int32_t)strlen((char*)offsetP) + 1; offsetP += strlen((char*)offsetP) + 1; } // Get the mimeTypes string if ( smsParamsP->mimeTypes && lenRemaining) { // Allocate extension string memory if ((smsParamsP->mimeTypes = (char*)MemPtrNew((size_t) (strlen((char*)offsetP) + 1))) == NULL) goto cleanup; memmove(smsParamsP->mimeTypes, offsetP, strlen((char*)offsetP) + 1); lenRemaining -= (int32_t)strlen((char*)offsetP) + 1; offsetP += strlen((char*)offsetP) + 1; } if (lenRemaining >= 0) return errNone; return exgErrBadParam; cleanup: // Free only what was really allocated if (smsParamsP->message.address1.size && smsParamsP->message.address1.numberP) { MemPtrFree(smsParamsP->message.address1.numberP); if (smsParamsP->message.address2.size && smsParamsP->message.address2.numberP) { MemPtrFree(smsParamsP->message.address2.numberP); if (smsParamsP->message.extensionCount && smsParamsP->message.extensionP) { MemPtrFree(smsParamsP->message.extensionP); if (smsParamsP->extension) { MemPtrFree(smsParamsP->extension); if (smsParamsP->mimeTypes) { MemPtrFree(smsParamsP->mimeTypes); } } } } } return exgMemError; }
SmsPrefType Struct
Purpose
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.
Declared In
SmsLib.h
Prototype
typedef struct SmsPrefType { uint32_t validity; uint16_t warnOver; Boolean leaveOnPhone; Boolean report; Boolean autoSmsCenter; uint8_t padding[3]; char smsCenterNumberP[kTelPhoneNumberMaxLen]; } SmsPrefType, *SmsPrefPtr
Fields
-
validity
- 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 day (86400 seconds).
-
warnOver
- 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.)
-
leaveOnPhone
- If
true
, any incoming messages retrieved from a phone remain on the phone as well. Iffalse
, the messages are deleted from the phone's inbox. -
report
- If
true
, the user receives confirmation that an SMS message was delivered. -
autoSmsCenter
- If
true
, don't use the value stored in thesmscNumberP
field. -
padding
- Padding bytes.
-
smsCenterNumberP
- A pointer to the message center to be used. If
NULL
or the empty string, the SMS message center set by the phone is used.
SMS Exchange Library Constants
SMS Control Constants
Purpose
These 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.
Declared In
SmsLib.h
Constants
-
#define exgLibSmsPrefGetOp (exgLibCtlSpecificOp | 1)
-
#define exgLibSmsPrefGetDefaultOp (exgLibCtlSpecificOp | 2)
-
#define exgLibSmsPrefSetOp (exgLibCtlSpecificOp | 3)
-
#define exgLibSmsPrefDisplayOp (exgLibCtlSpecificOp | 4)
-
#define exgLibSmsIncompleteGetCountOp (exgLibCtlSpecificOp | 5)
-
#define exgLibSmsIncompleteDeleteOp (exgLibCtlSpecificOp | 6)
Comments
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 5.1 ExgControl operations for SMS library
Returns a pointer to the SMS Exchange Libraries preferences in |
||
Returns the default values for the SMS Exchange Library preferences. |
||
Sets the SMS Exchange Library preferences to the values passed in |
||
One of the "Network Operator Types." Note that only |
Displays a form that allows the user to set the SMS preferences. |
|
Gets 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. |
||
Deletes the incomplete message with the ID passed in |
SMS Extension Types
Purpose
Defines Exchange Manager extensions that an application can register for to receive SMS messages of those types.
Declared In
SmsLib.h
Constants
-
#define kSmsRegExtensionTypeEMailInd "ewi"
- Email waiting indication.
-
#define kSmsRegExtensionTypeFaxInd "fwi"
- Fax waiting indication.
-
#define kSmsRegExtensionTypeFlash "fhs"
- Flash SMS message
-
#define kSmsRegExtensionTypeMessage "sms"
- SMS message.
-
#define kSmsRegExtensionTypeOtherInd "owi"
- Other message waiting indication.
-
#define kSmsRegExtensionTypeReport "rps"
- Report message.
-
#define kSmsRegExtensionTypeVoiceMailInd "vwi"
- Voice mail waiting indication.
SMS Extension Type Length
Purpose
Defines the length of an extension type constant value.
Declared In
SmsLib.h
Constants
SMS Message Types
Purpose
The SMS message type constants identify the type of message being sent. They are used in the requestType
field of the SmsParamsType
structure and can be combined with an OR operation.
Declared In
SmsLib.h
Constants
-
#define kSmsMessageTypeIn ((uint16_t) 0x0001)
- Classic message.
-
#define kSmsMessageTypeReport ((uint16_t) 0x0002)
- Report message.
-
#define kSmsMessageTypePart ((uint16_t) 0x0004)
- Internal use only; do not use. For multipart SMS reassembly.
-
#define kSmsMessageTypeMultipart ((uint16_t) 0x0008)
- An incomplete multipart message.
-
#define kSmsMessageTypeFlash ((uint16_t) 0x0010)
- Flash message.
-
#define kSmsMessageTypeIndication ((uint16_t) 0x0020)
- Indication that signals a message is waiting.
-
#define kSmsMessageTypeIncoming ((uint16_t) 0xFFFF)
- Internal use only; do not use. For getting an incoming message.
SMS Scheme
Purpose
Defines the Exchange Manager URL scheme for the SMS Exchange Library.
Declared In
SmsLib.h