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

5    SMS Exchange Library Reference

Telephony and SMS

Exploring Palm OS®

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

SmsParamsType Struct ^TOP^

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, 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.
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 to false (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 to false 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 to false 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 ^TOP^

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. If false, 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 the smscNumberP 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 ^TOP^

SMS Control Constants ^TOP^

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 

Operation

value Data Type

Description

exgLibSmsPrefGetOp

SmsPrefType

Returns a pointer to the SMS Exchange Libraries preferences in valueP, and creates the preferences and sets them to the default values if they do not exist.

exgLibSmsPrefGetDefaultOp

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.

exgLibSmsPrefDisplayOp

One of the "Network Operator Types." Note that only kTelNwkTypeGsmGprs is supported in Palm OS® Cobalt.

Displays a form that allows the user to set the SMS preferences.

exgLibSmsIncompleteGetCountOp

uint16_t. Output only.

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.

exgLibSmsIncompleteDeleteOp

uint16_t. Input only.

Deletes the incomplete message with the ID passed in valueP. Pass -1 to delete all incomplete messages.

SMS Extension Types ^TOP^

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

Purpose

Defines the length of an extension type constant value.

Declared In

SmsLib.h

Constants

#define kSmsRegExtensionTypeLength 3
The length of an extension type constant value.

SMS Message Types ^TOP^

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

Purpose

Defines the Exchange Manager URL scheme for the SMS Exchange Library.

Declared In

SmsLib.h

Constants

#define kSmsScheme "_sms"
The URL scheme for the SMS Exchange Library.