Documentation »  ACCESS Linux Platform Native Development »  Messaging Guide »  SMS

The Short Messaging Services (SMS) Postal Services (PS) plug-in provides services for SMS messages and Extended Messaging Service (EMS). The plug-in is a shared library dedicated to provide an API for using SMS within ACCESS Linux Platform.

The SMS PS plug-in simplifies third-party application development by hiding the complexity of data transport over SMS from postal services applications and the Exchange Manager. The plug-in also expands the functionality of wireless messaging, and provides a powerful API for handling SMS messages. Embedded services such as message fragmentation and re-assembly, persistence, and character set conversion are therefore completely transparent.

The SMS PS plug-in implements a generic Postal Services/Messaging API along with a specific API that allows any kind of messaging application to send an SMS message. The plug-in also manages a set of functions that can retrieve messages on a device, reassemble message fragments, and deliver complete messages. Through the Exchange Manager, any application can set up different "hooks" to handle specific types of incoming SMS messages prior to their delivery (e.g. WAP Push).

Supported Transactions ^TOP^

Types of transactions that can be sent from the SMS plug-in:

• Send request transaction: the originator sends an SMS
• Delivery Acknowledgement transaction: sent when the deferred option is set
• Read Report transaction: to confirm that an SMS has been read by the destination.

Types of transactions that can arrive to the SMS plug-in:

• Transaction Notification WAP Push; a new SMS has arrived
• Transaction Send-confirmation
• Transaction Retrieve-confirmation
• Transaction Read Originator, which corresponds to a Read Report confirmation
• Transaction Delivery Indicator, which corresponds to a Delivery Report confirmation.

Example: SMS Session ^TOP^

Most of the features of a service rely on a session. A session is a temporary object created by the Service object, which requires an Account.

If the creation of the session succeeds (some security could be introduced in this process), the session can be connected.

Using the session, you can send and receive envelopes, enumerate folders, and store envelopes.

Listing 5.1  Full sample: Create an SMS session, connect to it, and send an envelope

// Create the session using an existing account 
alp_postal_session_id_t sessionId; 
alp_postal_service_create_session(ALP_POSTAL_SERVICE_ID_SMS, account_id, 
&sessionId); 
 
// Connect the session (asynchronous call) 
// A dialog may appear: 'Turn phone on?' 
alp_postal_session_connect(ALP_POSTAL_SERVICE_ID_SMS, sessionId, NULL, NULL, 
NULL); 
 
// Build an envelope 
AlpPostalEnvelope env; 
build_sample_envelope(&env); 
 
// Send the envelope 
alp_postal_session_send_envelope(ALP_POSTAL_SERVICE_ID_SMS, sessionId, &env, 
NULL); 
// Free the envelope 
alp_postal_envelope_free(&env); 

Example: SMS Exchange Component ^TOP^

The SMS Exchange component interacts with the Exchange Manager. This component manages the translation table, which contains correspondence between Exchange Manager mime-types and SMS protocol elements or port numbers. For example, "text/vcard" represents the Exchange Manager mime-type for handling the vCard format in the platform, and"E2"is the SMS protocol port number for exchanging vCard information using SMS. Therefore in the translation table, there is an association between "text/vcard" and "E2" for vCard management.

The SMS Exchange component also manages platform hooks for SMS reception. Third-party applications can register to receive specific types of SMS messages as soon as the messages are received, and prior to delivering them to a messaging application.

The following example illustrates how to retrieve all entries in an NBS table, trace the entry properties, add a new entry, update the entry, and then remove it.

Listing 5.2  Retrieve all entries, trace entry properties, and add, update, and remove entries

AlpPostalEnumerator                entry_enum; 
     AlpPostalSmsExchangeEntry          entry; 
     alp_postal_sms_exchange_entry_id_t entry_id; 
     AlpPostalProperty* p; 
 
// Initialize an SMS exchange entry enumerator. This function MUST be called  
// before alp_postal_sms_exchange_table_entry_get_enumerator().  
alp_postal_sms_exchange_table_entry_init_enumerator(&entry_enum); 
// Get enumerator of the stored exchange table entries. 
alp_postal_sms_exchange_table_entry_get_enumerator(&entry_enum); 
 
// Return the exchange table entry for the current position and increment the 
// enumerator, then free the given exchange table entry. 
     while(alp_postal_sms_exchange_table_entry_get_next(&entry_enum, &entry) != 
     POSTAL_STATUS_DB_NO_RECORD) 
     { 
            alp_postal_sms_exchange_table_entry_get_property(&entry, 
             ALP_POSTAL_SMS_PROPERTY_EXCHANGE_PORT, &p); 
            printf("ALP_POSTAL_SMS_PROPERTY_EXCHANGE_PORT = %d.", 
             p->value.asInteger); 
 
            alp_postal_sms_exchange_table_entry_get_property(&entry, 
             ALP_POSTAL_SMS_PROPERTY_EXCHANGE_MIMETYPE, &p); 
            printf("ALP_POSTAL_SMS_PROPERTY_EXCHANGE_MIMETYPE = %s.",  
             p->value.asString); 
 
            alp_postal_sms_exchange_table_entry_get_property(&entry, 
             ALP_POSTAL_SMS_PROPERTY_EXCHANGE_FORCE_DELETE, &p); 
            printf("ALP_POSTAL_SMS_PROPERTY_EXCHANGE_FORCE_DELETE = %s.", 
              (p->value.asBool) ? "true":"false" ); 
 
            alp_postal_sms_exchange_table_entry_free(&entry); 
     } 
 
// Release the SMS exchange entry enumerator. [left off] 
     alp_postal_sms_exchange_table_entry_enumerator_release(&entry_enum); 
 
// Initialize an SMS exchange entry. 
     alp_postal_sms_exchange_table_entry_init(&entry); 
 
// Set a property to a Postal SmsExchangeEntry 
     alp_postal_sms_exchange_table_entry_set_property(&entry, 
        ALP_POSTAL_SMS_PROPERTY_EXCHANGE_PORT, (void*)123, 0); 
    alp_postal_sms_exchange_table_entry_set_property(&entry, 
        ALP_POSTAL_SMS_PROPERTY_EXCHANGE_MIMETYPE, "test/mime_type", 
        pspdk_string_length("test/mime_type")); 
     alp_postal_sms_exchange_table_entry_set_property(&entry, 
        ALP_POSTAL_SMS_PROPERTY_EXCHANGE_FORCE_DELETE, (void*)0, 0); 
      
// Add an exchange table entry to the stored exchange table list. 
     alp_postal_sms_exchange_table_entry_add_new(&entry); 
 
// Get the ID of an exchange table entry structure provided by the server. 
     alp_postal_sms_exchange_table_entry_get_id(&entry, &entry_id); 
     alp_postal_sms_exchange_table_entry_set_property(&entry, 
        ALP_POSTAL_SMS_PROPERTY_EXCHANGE_MIMETYPE, "test2/mime_type2", 
        pspdk_string_length("test2/mime_type2")); 
 
// Update a stored exchange table entry. 
      alp_postal_sms_exchange_table_entry_update(entry_id, &entry); 
 
// Delete a stored exchange table entry. 
    alp_postal_sms_exchange_table_entry_delete (entry_id); 
 
// Free the given exchange table entry. 
    alp_postal_sms_exchange_table_entry_free(&entry);