Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Creating an EMS Message

Messages longer than the SMS limit are sent using the Enhanced Messaging Service (EMS). EMS messages may include media content.

The ISMS interface supports EMS messages. The application must segment the message into pieces that fit within the SMS limit, add header information, and send each segment. The header information fits within the message payload, which means that the message segment and header information must be smaller than the SMS limit.

The concatenation information contains three eight-bit numbers:

  • A sequence number which starts at 1 and is incremented for each message segment.
  • The total number of segments.
  • A reference number which is the same for each segment within the message. This identifies the message.

The segments of a three segment message would have the values of:

  • 1,3,X
  • 2,3,X
  • 3,3,X
Where X is the reference number between 0 and 255.

Objective

This topic describes how to set up an EMS message.

Requirements

The application uses the ISMS interface to create and send messages. For each message segment the concatenation information must set, and, if media content is included, the media object must be encoded and added to one or more message segments.

Event handling

The application uses a callback function to know when a message segment has been sent or received.

Example - Calculating the number of message segments

Determine the size of the message the user has typed in:

 void CalculateTotalMessage(CApp *pMe) {
    int msgLength = 0;
    int msgLengthInBytes = 0;
    int objPosInBytes = 0;
    int maxLoad = pMe->m_nMaxPayloadBytes - UDH_CONCAT_LENGTH;

    //********************************************************************
    // Note:
    // pMe->m_objPos represents object offset/position in the message
    // Negative value of pMe->m_objPos indicates no object in the message.
    // Calculation of segmentation will be done in bytes,
    // - with respect to  ISMS_GetBytesAvailableForPayload( )
    //********************************************************************

    MEMSET(pMe->m_wszStringBuffer, 0, sizeof(pMe->m_wszStringBuffer));
    ITEXTCTL_GetText(pMe->m_pITextMsg,pMe->m_wszStringBuffer, sizeof (pMe->m_wszStringBuffer));

    msgLength = WSTRLEN(pMe->m_wszStringBuffer);

Based upon the Mobile Originated (MO) encoding, specify the size factor:

 switch (pMe->m_moEncoding) {
    case AEESMS_ENC_UNICODE:
       pMe->m_calculationFactor = 16;
       break;
    case AEESMS_ENC_ASCII:
    case AEESMS_ENC_GSM_7_BIT_DEFAULT:
       pMe->m_calculationFactor = 7;
       break;
    case AEESMS_ENC_OCTET:
    case AEESMS_ENC_LATIN:
       pMe->m_calculationFactor = 8;
       break;
    default:
    break;
 }

 msgLengthInBytes = msgLength *pMe->m_calculationFactor / 8;
 objPosInBytes = pMe->m_objPos *pMe->m_calculationFactor / 8;
 
 if ((pMe->m_moEncoding == AEESMS_ENC_ASCII)||
     (pMe->m_moEncoding ==AEESMS_ENC_GSM_7_BIT_DEFAULT)) {
    if (msgLength % 8 != 0){
       msgLengthInBytes++;
    }
    if (pMe->m_objPos %8 != 0) {
       objPosInBytes++;
    }
 }

If the user has specified media content, add the UDH size to the message size:

 // Include ems udh in the payload count
 if (pMe->m_objPos>=0) {
    if (AEESMS_UDH_SMALL_PICTURE == pMe->m_emsObj.header_id){
       msgLengthInBytes +=UDH_SM_PIC_ANIM_LENGTH;
       if ((maxLoad - (objPosInBytes % maxLoad)) < UDH_SM_PIC_ANIM_LENGTH) {
       //****************************************************
       // objPosInBytes is within segment a,
       // but since the remaining bytes < udh length for the object,
       // object needs to go in the next segment (a+1),
       // leaving some unfilled bytes in message segment a.
       //*******************************************************
          msgLengthInBytes += maxLoad - (objPosInBytes %maxLoad);
       }
    } elseif (AEESMS_UDH_LARGE_PICTURE ==pMe->m_emsObj.header_id) {
        msgLengthInBytes +=UDH_LG_PIC_ANIM_LENGTH;
        if ((maxLoad -(objPosInBytes % maxLoad)) < UDH_LG_PIC_ANIM_LENGTH) {
           msgLengthInBytes += maxLoad - (objPosInBytes %maxLoad);
        }
    }
 } // end if objPos >= 0

Determine the number of segments

 if (msgLengthInBytes<= pMe->m_nMaxPayloadBytes) {
    pMe->m_totalMsg = 1;
 } else {
    pMe->m_totalMsg = (msgLengthInBytes /maxLoad) + 1;
    if (msgLengthInBytes% (pMe->m_nMaxPayloadBytes -UDH_CONCAT_LENGTH) == 0) {
       pMe->m_totalMsg--;
    }
 }
} // end of calculate total messages

Example - Setting concatenation information

Set the concatenation information by calling the ISMS interface AddOpt function.

 void AddConcatUDH(CApp *pMe) {
     unsigned char concbuff[UDH_CONCAT_LENGTH+1];
     SMSMsgOpt smo[2];
     smo[1].nId = MSGOPT_END;
     smo[1].pVal = NULL;
 
     if (pMe->m_payloadEncoding == AEE_ENC_UNICODE){
        MSGOPT_SETUDHCONCAT16BUFFER(concbuff, pMe->m_seqNum,pMe->m_totalMsg,pMe->m_refNum);
     } else {
        MSGOPT_SETUDHCONCAT8BUFFER(concbuff, pMe->m_seqNum,pMe->m_totalMsg,pMe->m_refNum);
     }

     //*****************************************************
     // Remove any previously added concatenation UDH information
     //*****************************************************
     ISMSMSG_RemoveOpt(pMe->m_pISMSMsg,MSGOPT_UDH_CONCAT);

     smo[0].nId = MSGOPT_UDH_CONCAT;
     smo[0].pVal = concbuff;
     ISMSMSG_AddOpt(pMe->m_pISMSMsg,smo);
 }

Example - Setting media content information

Pictures displayed on the device are .bmp files. EMS pictures have a different format. The application must convert .bmp formatted pictures into the EMS format when sending the message.

EMS user pictures are black and white. EMS pictures are coded row by row from upper left to lower right. Each bit represents the color of the pixel and the most significant bit represents the pixel at the left. Zero represents a white pixel and one represents a black pixel. For more information, refer to the 3GPP TS 23.040 specification.

To add a small picture to a message:

 MSGOPT_SETUDHSMALLPICBUFFER(smpicbuff,position,pMe->m_emsObj.u.small_picture.data);
 smo[0].nId = MSGOPT_UDH_USERDEFINED;
 smo[0].pVal = (void *)smpicbuff;
 ISMSMSG_AddOpt(pMe->m_pISMSMsg,smo);