RMobileBroadcastMessaging Class Reference

class RMobileBroadcastMessaging : public RTelSubSessionBase

This sub-session provides access to the broadcast message services provided by GSM/WCDMA and CDMA networks.

Clients will open a RMobileBroadcastMessaging sub-session and then wait for incoming broadcast messages. The broadcast messages received can depend upon a "message filter" which defines the languages and/or identifiers of acceptable (or unacceptable) messages. This sub-session and the function members within this section must be supported if the TSY indicates that it supports the MobileBroadcastMessaging functional unit.

Inherits from

Public Member Functions
RMobileBroadcastMessaging()
IMPORT_C voidClose()
IMPORT_C TIntGetCaps(TDes8 &)
IMPORT_C TIntGetFilterSetting(TMobilePhoneBroadcastFilter &)
IMPORT_C voidGetLanguageFilter(TRequestStatus &, TDes16 &)
IMPORT_C voidNotifyBroadcastIdListChange(TRequestStatus &)
IMPORT_C voidNotifyFilterSettingChange(TRequestStatus &, TMobilePhoneBroadcastFilter &)
IMPORT_C voidNotifyLanguageFilterChange(TRequestStatus &, TDes16 &)
IMPORT_C TIntOpen(RMobilePhone &)
IMPORT_C voidReceiveMessage(TRequestStatus &, TDes8 &, TDes8 &)
IMPORT_C voidSetFilterSetting(TRequestStatus &, TMobilePhoneBroadcastFilter)
IMPORT_C voidSetLanguageFilter(TRequestStatus &, const TDesC16 &)
IMPORT_C voidStoreBroadcastIdListL(TRequestStatus &, CMobilePhoneBroadcastIdList *, TMobileBroadcastIdType)
Protected Member Functions
IMPORT_C voidConstructL()
IMPORT_C voidDestruct()
Private Member Functions
RMobileBroadcastMessaging(const RMobileBroadcastMessaging &)
Inherited Functions
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const
RTelSubSessionBase::Blank(const TInt,TReqPriorityType)const
RTelSubSessionBase::Blank(const TInt,TRequestStatus &,TReqPriorityType)const
RTelSubSessionBase::CancelAsyncRequest(TInt)const
RTelSubSessionBase::CancelReq(const TInt,const TInt)const
RTelSubSessionBase::CancelSubSession()const
RTelSubSessionBase::Get(const TInt,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::RTelSubSessionBase()
RTelSubSessionBase::ResetSessionHandle()
RTelSubSessionBase::SessionHandle()const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const RFile &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,TDes8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::SetSessionHandle(RSessionBase &)
RTelSubSessionBase::SubSessionHandle()
Public Member Enumerations
enumanonymous { KBroadcastPageSize = 88 }
enumanonymous { KGsmBroadcastDataSize = KBroadcastPageSize, KCdmaBroadcastDataSize = KBroadcastPageSize, KWCdmaBroadcastPageSize = KBroadcastPageSize }
enumTBroadcastMessagingFilterCaps { KCapsSimpleFilter = 0x00000001, KCapsLangFilter = 0x00000002, KCapsIdFilter = 0x00000004 }
enumTMobileBroadcastAttributeFlags { KBroadcastDataFormat = 0x00000001, KCdmaServiceCategory = 0x00000002 }
enumTMobileBroadcastDataFormat { EFormatUnspecified, EFormatGsmTpdu, EFormatCdmaTpdu, EFormatWcdmaTpdu }
enumTMobileBroadcastIdType { EGsmBroadcastId, ECdmaBroadcastId }
enumTMobileBroadcastModeCaps { KCapsGsmTpduFormat = 0x00000001, KCapsCdmaTpduFormat = 0x00000002, KCapsWcdmaTpduFormat = 0x00000004 }
enumTMobilePhoneBroadcastFilter { EBroadcastFilterUnspecified, EBroadcastAcceptNone, EBroadcastAcceptAll, EBroadcastAcceptFilter, EBroadcastRejectFilter }
Inherited Enumerations
RTelSubSessionBase:TReqPriorityType
Public Member Type Definitions
typedef TBuf8< KBroadcastPageSize > TBroadcastPageData
typedef TBuf8< KCdmaBroadcastDataSize > TCdmaBroadcastMessageData
typedef TBuf8< KGsmBroadcastDataSize > TGsmBroadcastMessageData
typedef TPckg< TMobileBroadcastAttributesV1 > TMobileBroadcastAttributesV1Pckg
typedef TPckg< TMobileBroadcastAttributesV2 > TMobileBroadcastAttributesV2Pckg
typedef TPckg< TMobileBroadcastCapsV1 > TMobileBroadcastCapsV1Pckg
typedef TBuf8< KWCdmaBroadcastPageSize > TWCdmaBroadcastPageData
Private Attributes
CCbsMessagingPtrHolder *iCbsMessagingPtrHolder
Inherited Attributes
RTelSubSessionBase::iPtrHolder

Constructor & Destructor Documentation

RMobileBroadcastMessaging()

IMPORT_CRMobileBroadcastMessaging()

Standard constructor.

RMobileBroadcastMessaging(const RMobileBroadcastMessaging &)

RMobileBroadcastMessaging(const RMobileBroadcastMessaging &)[private]

Parameters

const RMobileBroadcastMessaging &

Member Functions Documentation

Close()

IMPORT_C voidClose()
This function member closes a RMobileBroadcastMessaging object.
capability
None

ConstructL()

IMPORT_C voidConstructL()[protected]

Destruct()

IMPORT_C voidDestruct()[protected]

Destructor. Deletes any dynamically allocated memory.

GetCaps(TDes8 &)

IMPORT_C TIntGetCaps(TDes8 &aCaps)const

This function member gets a class that reflects the broadcast messaging capabilities of the phone.

TMobileBroadcastCapsV1
capability
None

Parameters

TDes8 & aCapsOn completion, a TMobileBroadcastCapsV1Pckg with the broadcast messaging capabilities.

GetFilterSetting(TMobilePhoneBroadcastFilter &)

IMPORT_C TIntGetFilterSetting(TMobilePhoneBroadcastFilter &aSetting)const

This function member gets the current setting for the receipt of broadcast messages.

This setting will indicate whether all or no messages are being accepted or whether only those messages specified by the filters are going to be accepted or rejected.

If the returned setting, aSetting, equals EBroadcastAcceptFilter then the phone will accept messages whose identifier is included within the identifier list AND whose language is included within the language filter. If the returned setting, aSetting, equals EBroadcastRejectFilter then the phone will reject messages whose identifier is included within the identifier list OR whose language is included within the language filter.

N.B. If the phone supports both GSM/WCDMA and CDMA mode then it will probably need two identifier lists - one to contain a list of CBMI (for GSM/WCDMA mode) and the other to contain a list of Service Categories (for CDMA mode) This function member is synchronous because it is expected that this will be a TSY specific setting whose current value the TSY has previously determined.

capability
ReadUserData

Parameters

TMobilePhoneBroadcastFilter & aSettingOn completion, the current filter settings.

GetLanguageFilter(TRequestStatus &, TDes16 &)

IMPORT_C voidGetLanguageFilter(TRequestStatus &aReqStatus,
TDes16 &aLangFilter
)const

This function member allows a client to retrieve the current contents of the broadcast message language filter.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingGetLanguageFilter) to cancel a previously placed asynchronous GetLanguageFilter() request.

capability
ReadUserData

Parameters

TRequestStatus & aReqStatusOn return KErrNone if successful, KErrNotFound if there is no language filter in place, and KErrNotSupported if the phone does not support a language filter.
TDes16 & aLangFilterOn completion, contain as many languages (each coded on 16-bits) as can fit in the descriptor supplied by the client. This filter defines which are the desired (or undesired) language(s) of incoming broadcast messages. A language is defined either within one byte by its Cell Broadcast Data Coding Scheme (as defined in GSM 03.38) or within two bytes by its ISO 639 alphanumeric pair. Even if a language is represented by an 8-bit value it will be returned as a 16-bit value with the language in the least significant 8-bits.

NotifyBroadcastIdListChange(TRequestStatus &)

IMPORT_C voidNotifyBroadcastIdListChange(TRequestStatus &aReqStatus)const

This function member allows a client to be notified that changes have been made to the BroadcastId filter identifier list.

When it completes, it does not return the new version of the list so the client will have to retrieve the list using CRetrieveMobilePhoneBroadcastIdL again if it is interested in the new list.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingNotifyIdListChange) to cancel a previously placed asynchronous NotifyBroadcastIdListChange() request.

capability
None

Parameters

TRequestStatus & aReqStatusOn return, KErrNone if successful, a system wide error code if not.

NotifyFilterSettingChange(TRequestStatus &, TMobilePhoneBroadcastFilter &)

IMPORT_C voidNotifyFilterSettingChange(TRequestStatus &aReqStatus,
TMobilePhoneBroadcastFilter &aSetting
)const

This function member allows a client to be notified if there is a change in the setting for the receipt of broadcast messages.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingNotifyFilterSettingChange) to cancel a previously placed asynchronous NotifyFilterSetting() request.

capability
ReadUserData

Parameters

TRequestStatus & aReqStatusOn return, KErrNone if successful, KErrNotSupported if the phone does not support a filter setting.
TMobilePhoneBroadcastFilter & aSettingOn completion, the changed filter setting.

NotifyLanguageFilterChange(TRequestStatus &, TDes16 &)

IMPORT_C voidNotifyLanguageFilterChange(TRequestStatus &aReqStatus,
TDes16 &aLangFilter
)const

This function member allows a client to be notified if there is a change in the contents of the language filter.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingNotifyLanguageFilterChange) to cancel a previously placed asynchronous NotifyLanguageFilterChange() request.

capability
ReadUserData

Parameters

TRequestStatus & aReqStatusOn return, KErrNone, if successful, KErrNotSupported if the phone does not support a language filter.
TDes16 & aLangFilterOn completion, the new language filter.

Open(RMobilePhone &)

IMPORT_C TIntOpen(RMobilePhone &aPhone)

This function member opens a Broadcast Messaging object. The name of the sub-session opened in the TSY will equal the string defined by the KETelBroadcastMessaging LIT definition.

capability
None

Parameters

RMobilePhone & aPhoneThe existing RMobilePhone session.

ReceiveMessage(TRequestStatus &, TDes8 &, TDes8 &)

IMPORT_C voidReceiveMessage(TRequestStatus &aReqStatus,
TDes8 &aMsgData,
TDes8 &aMsgAttributes
)const

This function member enables the client to receive the next incoming broadcast message from the network.

The request will be completed when a new message arrives. The client will pass a descriptor of size KBroadcastPageSize bytes, provided by the typedef TBroadcastPageData, to hold the returned broadcast message data into the aMsgData parameter.

This buffer size should be used for all types of messages: GSM, CDMA and WCDMA.

The function explicity checks that the aMsgData parameter is of size KBroadcastPageSize. If the buffer size does not equal KBroadcastPageSize, the client request will be completed with KErrArgument.

A TSY should handle ReceiveMessage() requests by making them repost immediately (to ensure none are missed) and possibly multiple completion enabled. When a new message arrives the TSY will copy the broadcast message contents into its stored pointer to the broadcast message data, fill in the broadcast message attributes and then complete the request.

Parameters

TRequestStatus & aReqStatusOn return, KErrNone if successful, KErrArgument if the aMsgData buffer size does not equal KBroadcastPageSize, otherwise a system wide error code.
TDes8 & aMsgDataOn completion, the message data.
TDes8 & aMsgAttributesOn completion, the broadcast message attributes, in an instance of the TMobileBroadcastAttributesV1Pckg class.

SetFilterSetting(TRequestStatus &, TMobilePhoneBroadcastFilter)

IMPORT_C voidSetFilterSetting(TRequestStatus &aReqStatus,
TMobilePhoneBroadcastFilteraSetting
)const

This function member sets a new setting for the receipt of broadcast messages.

This setting will specify whether all or no messages are being accepted or whether only those messages specified by the filters are going to be accepted or rejected.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingSetFilterSetting) to cancel a previously placed asynchronous SetFilterSetting() request.

capability
WriteUserData

Parameters

TRequestStatus & aReqStatusOn return, the KErrNone if successful, KErrNotSupported if the phone does not support a filter setting.
TMobilePhoneBroadcastFilter aSettingOn completion, the new filter setting of the phone.

SetLanguageFilter(TRequestStatus &, const TDesC16 &)

IMPORT_C voidSetLanguageFilter(TRequestStatus &aReqStatus,
const TDesC16 &aLangFilter
)const

This function member allows a client to store new contents for the broadcast message language filter.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingSetLanguageFilter) to cancel a previously placed asynchronous SetLanguageFilter() request.

capability
WriteUserData

Parameters

TRequestStatus & aReqStatusOn return, KErrNone, if successful, KErrNotSupported if the phone does not support a language filter.
const TDesC16 & aLangFilterEach element in this descriptor will define a language. This filter will define which are the desired (or undesired) language(s) of incoming broadcast messages.

StoreBroadcastIdListL(TRequestStatus &, CMobilePhoneBroadcastIdList *, TMobileBroadcastIdType)

IMPORT_C voidStoreBroadcastIdListL(TRequestStatus &aReqStatus,
CMobilePhoneBroadcastIdList *aIdList,
TMobileBroadcastIdTypeaIdType
)

This function member may be used to store a new version of the entire BroadcastId list of identifier entries.

The list, should not contain more entries than can be stored phone-side. This function member will store all the identifier list entries into the phone-side storage. It will overwrite the current contents of the storage and may cause other clients to be notified of the change in identifier list.

Due to the probable time taken to store a list, there is only an asynchronous version of this function member. This function member will leave if an out of memory error occurs during allocation of a client-side buffer in which to store the streamed list contents.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileBroadcastMessagingStoreIdList) to cancel a previously placed asynchronous StoreBroadcastIdListL() request. Will leave if the CBufFlat to hold the streamed contents can not be allocated

capability
WriteUserData

Parameters

TRequestStatus & aReqStatusOn return, KErrNone if successful, a system wide error code if not.
CMobilePhoneBroadcastIdList * aIdListThe list of BroadcastId identifier entries to be stored.
TMobileBroadcastIdType aIdTypeSpecifies whether the list is to be stored as a GSM/WCDMA list of CBMI entries or a CDMA list of Service Category entries.

Member Enumerations Documentation

Enum anonymous

A constant which defines the length of the buffer to be passed to ReceiveMessage.

This constant should be used for all message types: GSM, CDMA and WCDMA.

Enumerators

KBroadcastPageSize = 88

Enum anonymous

Old buffer sizes. KBroadcastPageSize should be used instead.

Enumerators

KGsmBroadcastDataSize = KBroadcastPageSize
KCdmaBroadcastDataSize = KBroadcastPageSize
KWCdmaBroadcastPageSize = KBroadcastPageSize

Enum TBroadcastMessagingFilterCaps

Broadcast message filter capabilities.

Modes: Common

RMobileBroadcastMessaging::GetLanguageFilter()

Enumerators

KCapsSimpleFilter = 0x00000001

Phone supports switching broadcast messages on or off. This means the EbroadcastAcceptNone and EBroadcastAcceptAll settings of TMobilePhoneBroadcastFilter are supported.

Modes: Common

KCapsLangFilter = 0x00000002

Phone supports filtering of broadcast messages depending upon their language. The language filter is a list of languages used only for broadcast filtering.

Modes: Common

RMobileBroadcastMessaging::GetLanguageFilter()

KCapsIdFilter = 0x00000004

Phone supports filtering of broadcast messages depending upon their subject. The subject of a message is identified in GSM/WCDMA mode by the Cell Broadcast Message Identifier (CBMI) and in CDMA mode by the Service Category.

Modes: Common

Enum TMobileBroadcastAttributeFlags

Defines the broadcast attributes.

Modes: Common

Enumerators

KBroadcastDataFormat = 0x00000001

The iFormat field is valid in the attribute class.

Modes: Common

KCdmaServiceCategory = 0x00000002

The iServiceCategory field is valid in the attribute class.

Modes: CDMA 9.5

Enum TMobileBroadcastDataFormat

The mobile broadcast data format, used byTMobileBroadcastAttributesV1.

Modes: Common

Enumerators

EFormatUnspecified

The message data format is not specified.

Modes: Common

EFormatGsmTpdu

The message data format complies to a Cell Broadcast TPDU coded as 88 octets (6 for header and 82 for message data) according to GSM 03.41.

Modes: GSM/WCDMA

EFormatCdmaTpdu

The message data format complies to IS-637-A encoding of the Bearer Data parameter within the Transport Layer's SMS-Broadcast message.

Modes: CDMA 9.5

EFormatWcdmaTpdu

The message data format complies to a Cell Broadcast TPDU coded as 1252 octets (6 for header and a maximum of 1246 for message data) according to 3GPP 25.324.

Modes: WCDMA

Enum TMobileBroadcastIdType

Defines the broadcast types.

Enumerators

EGsmBroadcastId

GSM broadcast.

ECdmaBroadcastId

CDMA broadcast. 9.5

Enum TMobileBroadcastModeCaps

Broadcast capabilities.

Modes:GSM/WCDMA

Enumerators

KCapsGsmTpduFormat = 0x00000001

GSM 03.41 cell broadcast messages are supported.

Modes:GSM/WCDMA

KCapsCdmaTpduFormat = 0x00000002

IS-637-A broadcast messages are supported.

Modes:CDMA 9.5

KCapsWcdmaTpduFormat = 0x00000004

3GPP 25.324 Release 4 cell broadcast messages are supported.

Modes: WCDMA

Enum TMobilePhoneBroadcastFilter

The filter settings of the mobile phone.

Modes: Common

Enumerators

EBroadcastFilterUnspecified

The phone does not have a filter setting.

EBroadcastAcceptNone

The phone is not accepting any broadcast messages.

EBroadcastAcceptAll

The phone is accepting all broadcast messages.

EBroadcastAcceptFilter

The phone is accepting those broadcast messages included within the language and identifier filters.

EBroadcastRejectFilter

The phone is rejecting those broadcast messages included within the language or identifier filters.

Member Type Definitions Documentation

Typedef TBroadcastPageData

typedef TBuf8< KBroadcastPageSize >TBroadcastPageData

Buffer for received messages.

This buffer should be used for all message types: GSM, CDMA and WCDMA.

Typedef TCdmaBroadcastMessageData

typedef TBuf8< KCdmaBroadcastDataSize >TCdmaBroadcastMessageData

Buffer for CDMA messages. TBroadcastPageData should be used instead. 9.5

Typedef TGsmBroadcastMessageData

typedef TBuf8< KGsmBroadcastDataSize >TGsmBroadcastMessageData

Buffer for GSM messages. TBroadcastPageData should be used instead.

Typedef TMobileBroadcastAttributesV1Pckg

typedef TPckg< TMobileBroadcastAttributesV1 >TMobileBroadcastAttributesV1Pckg

A typedef'd packaged TMobileBroadcastAttributesV1 for passing through a generic API function member.

Typedef TMobileBroadcastAttributesV2Pckg

typedef TPckg< TMobileBroadcastAttributesV2 >TMobileBroadcastAttributesV2Pckg

A typedef'd packaged TMobileBroadcastAttributesV1 for passing through a generic API function member.

Typedef TMobileBroadcastCapsV1Pckg

typedef TPckg< TMobileBroadcastCapsV1 >TMobileBroadcastCapsV1Pckg

A typedef'd packaged TMobileBroadcastCapsV1 for passing through a generic API function member.

Typedef TWCdmaBroadcastPageData

typedef TBuf8< KWCdmaBroadcastPageSize >TWCdmaBroadcastPageData

Buffer for WCDMA messages. TBroadcastPageData should be used instead.

Member Data Documentation

CCbsMessagingPtrHolder * iCbsMessagingPtrHolder

CCbsMessagingPtrHolder *iCbsMessagingPtrHolder[private]