Multimode Messaging

SMS messaging

RMobileSmsMessaging provides access to the Short Message Service provided by GSM, WCDMA and CDMA networks.

In CDMA mode, SMS has three protocol layers: Relay lowest level, Transport and Teleservice. Relay is the lowest level while Transport and Teleservice are application level. RMobileSmsMessaging provides an interface to the Transport layer. Usually, the Teleservice layer is implemented in a sockets protocol module. The Teleservice layer, rather than RMobileSmsMessaging, would be the interface used by applications to send SMS messages. SMS messages are passed across the API as Packet Data Units (PDUs).

Segmentation and reassembly of long SMS messages over 255 bytes is not provided by the API, and must be provided by a higher-level module such as the smsprot.prt protocol module.

RMobileSmsMessaging allows clients to:

• open an SMS sub-session using RMobileSmsMessaging::Open()

• retrieve capabilities using RMobileSmsMessaging::GetCaps(). Capabilities are encapsulated in a packaged RMobileSmsMessaging::TMobileSmsCapsV1 object.

• retrieve the mode the phone uses to handle incoming SMS messages before passing them on to TSY using RMobileSmsMessaging::GetReceiveMode().

• set the mode the phone uses to handle incoming SMS messages before passing them on to TSY using RMobileSmsMessaging::SetReceiveMode()

• wait for the next incoming SMS message using RMobileSmsMessaging::ReceiveMessage()

• send a positive acknowledgement for an SMS after successful decoding and storage using RMobileSmsMessaging::AckSmsStored()

• send a negative acknowledgement for an SMS after failure in decoding and storage using RMobileSmsMessaging::NackSmsStored()

• tell the network to resume transferring SMS to the phone, after reception has been suspended because SMS storage is full using RMobileSmsMessaging::ResumeSmsReception()

• get the bearer type which is CSD or packet-switched for sending SMS messages using RMobileSmsMessaging::SetMoSmsBearer()

• set the bearer type using RMobileSmsMessaging::SetMoSmsBearer()

• be notified if the bearer type changes using RMobileSmsMessaging::NotifyMoSmsBearerChange()

• send an SMS message to the network using RMobileSmsMessaging::SendMessage()

• get the number of phone-side SMS message stores using RMobileSmsMessaging::EnumerateMessageStores()

• get information about a specified SMS message store indicated using RMobileSmsMessaging::GetMessageStoreInfo(). Such information is encapsulated in a packaged RMobilePhoneStore::TMobilePhoneStoreInfoV1 object.

• get a list of GSM-specific SMS parameters stored in SIM . Examples of these parameters are Service Centre Address. Clients use CRetrieveMobilePhoneSmspList to get the list and returns a CMobilePhoneSmspList object. Each parameter is encapsulated in an RMobileSmsMessaging::TMobileSmspEntryV1 object.

Example

The following code sends the message aPdu to the destination aDest over GSM.

The code assumes iMobilePhone is an RMobilePhone object.

void CClientApp::SendSMSL(
        const RMobileSmsMessaging::TMobileSmsGsmTpdu& aPdu, 
        const TDesC& aDest)
    {
    // Open SMS session
    RMobileSmsMessaging smsSession;
    User::LeaveIfError(smsSession.Open(iMobilePhone));
    CleanupClosePushL(smsSession);

    // Get SMS capabilities
    RMobileSmsMessaging::TMobileSmsCapsV1 smsCaps;
    RMobileSmsMessaging::TMobileSmsCapsV1Pckg smsCapsPckg(smsCaps);
    User::LeaveIfError(smsSession.GetCaps(smsCapsPckg));

    // Test if SMS can be sent over GSM
    if ( smsCaps.iSmsMode & RMobileSmsMessaging::KCapsGsmSms
        & ( (smsCaps.iSmsControl & RMobileSmsMessaging::KCapsSendWithAck ) || 
            (smsCaps.iSmsControl & RMobileSmsMessaging::KCapsSendNoAck )))
        {
        // Set the required bearer
        TRequestStatus status;
        smsSession.SetMoSmsBearer(status, RMobileSmsMessaging::ESmsBearerCircuitPreferred);
        User::WaitForRequest(status);
        User::LeaveIfError(status.Int());

        // Set destination address and data format attributes
        RMobileSmsMessaging::TMobileSmsSendAttributesV1 sendAtts;
        sendAtts.iDestination.iTelNumber = aDest;
        sendAtts.iDataFormat = RMobileSmsMessaging::EFormatGsmTpdu;
        RMobileSmsMessaging::TMobileSmsSendAttributesV1Pckg sendAttsPckg(sendAtts);

        // Send the message
        smsSession.SendMessage(status, aPdu, sendAttsPckg);
        User::WaitForRequest(status);
        User::LeaveIfError(status.Int());
        }
     
    // Clean up
    CleanupStack::PopAndDestroy(); // calls smsSession.Close()
    }

Broadcast messaging

RMobileBroadcastMessaging provides access to the broadcast messaging services provided by GSM, WCDMA and CDMA networks.

Clients open an RMobileBroadcastMessaging sub-session and then wait for incoming broadcast messages. The broadcast messages received can depend on a message filter that defines the languages and identifiers of acceptable and unacceptable messages.

RMobileBroadcastMessaging allows clients to:

• open a broadcast messaging sub-session using RMobileBroadcastMessaging::Open()

• get capabilities using RMobileBroadcastMessaging::GetCaps(). Capabilities are encapsulated in a packaged RMobileBroadcastMessaging::TMobileBroadcastCapsV1 object.

• wait for the next incoming broadcast message using RMobileBroadcastMessaging::ReceiveMessage()

• get filter on and off settings using RMobileBroadcastMessaging::GetFilterSetting()

• set filter on and off settings using RMobileBroadcastMessaging::SetFilterSetting()

• be notified when the filter on and off settings change using RMobileBroadcastMessaging::NotifyFilterSettingChange()

• get the broadcast message language filter using RMobileBroadcastMessaging::GetLanguageFilter()

• set the broadcast message language filter using RMobileBroadcastMessaging::SetLanguageFilter()

• be notified when the message language filter changes using RMobileBroadcastMessaging::NotifyLanguageFilterChange()

• retrieve a list of identifiers by which to filter messages. Clients use CRetrieveMobilePhoneBroadcastIdList to get the list, a CMobilePhoneBroadcastIdList object. Each identifier is encapsulated in an RMobileBroadcastMessaging::TMobileBroadcastIdEntryV1 object.

• store a new version of the entire list of filter identifiers using RMobileBroadcastMessaging::StoreBroadcastIdListL()

• be notified if the filter identifier list changes using RMobileBroadcastMessaging::NotifyBroadcastIdListChange()

Example

The following code gets the contents of the next GSM broadcast message received in aMessageData.

void CClientApp::ReceiveBroadcastMessageL(RMobileBroadcastMessaging::TGsmBroadcastMessageData& aMessageData)
    {
    // Open session
    RMobileBroadcastMessaging bmSession;
    User::LeaveIfError(bmSession.Open(iMobilePhone));
    CleanupClosePushL(bmSession);

    // Get BM capabilities
    RMobileBroadcastMessaging::TMobileBroadcastCapsV1 bmCaps;
    RMobileBroadcastMessaging::TMobileBroadcastCapsV1Pckg bmCapsPckg(bmCaps);
    User::LeaveIfError(bmSession.GetCaps(bmCapsPckg));

    // Test if GSM 03.41 cell broadcast messages are supported
    if (bmCaps.iModeCaps & RMobileBroadcastMessaging::KCapsGsmTpduFormat)
        {
        // Get the next received broadcast message
        RMobileBroadcastMessaging::TMobileBroadcastAttributesV1 bmAtts;
        RMobileBroadcastMessaging::TMobileBroadcastAttributesV1Pckg bmAttsPckg(bmAtts);
        TRequestStatus status;
        bmSession.ReceiveMessage(status, aMessageData, bmAttsPckg);
        User::WaitForRequest(status);
        User::LeaveIfError(status.Int());
        }
     
    // Clean up
    CleanupStack::PopAndDestroy(); // calls bmSession.Close()
    }

USSD messaging

The Unstructured Supplementary Service Data (USSD) service provided by GSM/ WCDMA networks transmits information over the network signalling channels.

USSD is incorporated in the messaging functionality because of its potential use as a bearer for WAP or other overlying protocol. The USSD protocol is therefore suitable for implementation within a Sockets protocol (.PRT) module.

RMobileUssdMessaging allows clients to:

• open a USSD messaging sub-session using RMobileUssdMessaging::Open()

• get capabilities using RMobileUssdMessaging::GetCaps(). Capabilities are encapsulated in a packaged RMobileUssdMessaging::TMobileUssdCapsV1 object.

• wait for the next incoming USSD message using RMobileUssdMessaging::ReceiveMessage()

• send a UUSD message using RMobileUssdMessaging::SendMessage()

Example

The following code gets in aMessageData the contents, and in aUssdAtts the attributes, of the next USSD message received.

void CClientApp::ReceiveUssdMessageL(
    RMobileUssdMessaging::TGsmUssdMessageData& aMessageData,
    RMobileUssdMessaging::TMobileUssdAttributesV1& aUssdAtts)
    {
    // Open session
    RMobileUssdMessaging ussdSession;
    User::LeaveIfError(ussdSession.Open(iMobilePhone));
    CleanupClosePushL(ussdSession);

    // Get ussd capabilities
    RMobileUssdMessaging::TMobileUssdCapsV1 ussdCaps;
    RMobileUssdMessaging::TMobileUssdCapsV1Pckg ussdCapsPckg(ussdCaps);
    User::LeaveIfError(ussdSession.GetCaps(ussdCapsPckg));

    // Test if USSD messages can be received
    if (ussdCaps.iUssdTypes & RMobileUssdMessaging::KCapsMTUssd)
        {
        // Get the next received Ussd message
        RMobileUssdMessaging::TMobileUssdAttributesV1Pckg ussdAttsPckg(aUssdAtts);
        TRequestStatus status;
        ussdSession.ReceiveMessage(status, aMessageData, ussdAttsPckg);
        User::WaitForRequest(status);
        User::LeaveIfError(status.Int());
        }
     
    // Clean up
    CleanupStack::PopAndDestroy(); // calls ussdSession.Close()
    }