Collapse all Symbian^3 Application Developer Library

CMmsCodecClient Class Reference

class CMmsCodecClient : public CActive

This is a class declaration of CMmsCodecClient . It is a part of MMS Engine and it used for adding, fetching and sending multimedia messages from and into the message store in binary format. Also move, replace and some flag modifications provided.

The exported functions may be called in any order EXCEPT CreateNewMessageEntryL() MUST be called BEFORE AddMML() . If this rule is violated the operation may not be continued. The chunked transfer also must be done in order as described below. One message must be complete before another one is transferred.

Chunked transfer added to version 3.2. To support synchronizing large messages without the need of large linear buffer, chunked mode of data transfer has been added to the API

Chunked transfer from phone to PC:

1) Initialize retrieve (InitializeChunkedRetrievingL) 2) get a data chunk (GetNextDataPart) 3) release data chunk (ReleaseData) repeat steps 2 and 3 until all data has been processed

Chunked transfer from PC to phone: The same procedure can be used both for creating new entries or replacing existing entries.

1) Create an entry or specify an entry to be replaced (InitializeChunkedAddingL or InitializeChunkedReplacingL) 2) Give next data chunk until last one has been reached (NextDataPart)

If a chunked transfer to either direction is not totally completed before a new operation starts, the new operation will reset the state of the previous operation and delete possible incomplete entry. The next operation will proceed normally.

Setting the flags: Some information is not transferred inside the binary data in message headers. That's why some data is transferred in flags. The flag info is moved to the codec client in AddMML, ReplaceMML and SetFlags functions. To the caller the info is transferred in RetrieveMML function. The unread flag is starightforward, it is just a boolean which tells if the message has been read or not. The other flags (TUint32) is just like TMsvEntry.iMtmData1 (See mmsconst.h). but only the following bits are used, others are zero: EMmsDrmCorruptedAttachment , if the corrupted DRM attachments has been removed KMmsMessageMobileTerminated , modbile terminated message KMmsMessageEditorOriented , mobile originated message The last two must be set exclusive e.g the may not be set at the same time

Folders: User of this class may only access messages in the standard folders: KMsvGlobalInBoxIndexEntryId = 0x1002 KMsvGlobalOutBoxIndexEntryId=0x1003 KMsvDraftEntryId= 0x1004 KMsvSentEntryId=0x1005

mmscodecclient.lib

Inherits from

CMmsCodecClient
- CActive
  - CBase

Public Member Functions
	~CMmsCodecClient ()
IMPORT_C void	AddMML ( CBufFlat &, TMsvId , TUint32 , TBool , TMsvId &, TRequestStatus &)
IMPORT_C TInt	CreateNewMessageEntryL ( TMsvId , TMsvId &)
IMPORT_C TInt	DeleteMM ( TMsvId )
IMPORT_C TInt	DiskSpaceBelowCriticalLevelL ( TInt )
IMPORT_C TInt	GetNextDataPart ( TPtrC8 &, TBool &)
IMPORT_C void	InitializeChunkedAddingL ( TMsvId , TMsvId &, TUint32 , TBool )
IMPORT_C void	InitializeChunkedReplacingL ( TMsvId , TUint32 , TBool )
IMPORT_C void	InitializeChunkedRetrievingL ( TMsvId , TMsvId &, TUint32 &, TBool &, TInt &, TRequestStatus &)
IMPORT_C void	MoveMML ( TMsvId , TMsvId , TRequestStatus &)
IMPORT_C CMmsCodecClient *	NewL ( CMsvSession &)
IMPORT_C TInt	NextDataPart ( TPtrC8 &, TBool )
IMPORT_C TInt	ReleaseData ()
IMPORT_C void	ReplaceMML ( TMsvId &, CBufFlat &, TUint32 , TBool , TRequestStatus &)
IMPORT_C void	RetrieveMML ( TMsvId , CBufFlat &, TMsvId &, TUint32 &, TBool &, TRequestStatus &)
IMPORT_C CMsvOperation *	SendMML ( TMsvId , TRequestStatus &)
IMPORT_C TInt	SetFlags ( TMsvId , TUint32 , TBool )

Protected Member Functions
void	DoCancel ()
TInt	RunError ( TInt )
void	RunL ()

Private Member Functions
	CMmsCodecClient ()
void	ConstructL ( CMsvSession &)
void	DeleteCurrentEntryL ()
void	FinalizeDecodedMML ()
void	GenerateRecipientsL ( TDes &)
void	GenerateSenderL ( TDes &)
TBool	ParentOutbox ( TMsvId )
void	ReleaseRetrievedEntry ()
void	ResetChunkedMode ()
void	RetrieveFlags ( TMsvEntry , TUint32 &, TBool &)
void	SetFlagsToTMsvEntry ( TMsvEntry &)

Inherited Functions
	CActive::CActive(TInt)
	CActive::Cancel()
	CActive::Deque()
	CActive::Extension_(TUint,TAny &,TAny )
	CActive::IsActive()const
	CActive::IsAdded()const
	CActive::Priority()const
	CActive::SetActive()
	CActive::SetPriority(TInt)
	CActive::~CActive()
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Member Enumerations
enum	TState { EIdle = 0, EFinalizeDecodedMM , EFinalizeEncodedMM , ESendMM , EEntryCreated , EChunkedRetrieve , EChunkedAdd , EChunkedReplace }

Inherited Enumerations
	CActive:TPriority

Private Attributes
CMsvEntry *	iClientEntry
CMmsClientEntry *	iClientEntryWrapper
CClientMtmRegistry *	iClientMtmRegistry
TRequestStatus *	iClientStatus
CMmsDecode *	iDecoder
CBufFlat *	iEncodeBuffer
CMmsEncode *	iEncoder
TMsvId	iEntryBeingHandled
TUint32	iFlags
TMsvId	iFolder
RFs	iFs
TBool	iLastChunk
CMmsClientMtm *	iMmsClient
CMmsHeaders *	iMmsHeaders
TInt16	iMmsVersion
CMsvSession *	iMsvSession
TInt	iPosition
TState	iState
TBool	iUnread

Inherited Attributes
	CActive::iStatus

Constructor & Destructor Documentation

CMmsCodecClient()

CMmsCodecClient

(

)

[private]

C++ default constructor. C++ default constructor can NOT contain any code, that might leave.

~CMmsCodecClient()

~CMmsCodecClient

(

)

[virtual]

Destructor.

Member Functions Documentation

AddMML(CBufFlat &, TMsvId, TUint32, TBool, TMsvId &, TRequestStatus &)

IMPORT_C void	AddMML	(	CBufFlat &	aMm,
			TMsvId	aFolder,
			TUint32	aFlags,
			TBool	aUnread,
			TMsvId &	aMmId,
			TRequestStatus &	aStatus
		)

Add a multimedia message. The given multimedia message is stored to the target folder. The flags are set correctly. CreateNewMessageEntryL must be called before this function.

Return values:

Parameters

CBufFlat & aMm	the MM in binary format, which will be added to the messaging store
TMsvId aFolder	the folder in which the MM will be stored
TUint32 aFlags	the flags of the MM, which go to iMtmData1
TBool aUnread	if the MM is unread or not
TMsvId & aMmId	the index, which was created for the added MM by the caller.
TRequestStatus & aStatus	request status of the calling active object

ConstructL(CMsvSession &)

void

ConstructL

(

CMsvSession &

aMsvSession

)

[private]

By default Symbian 2nd phase constructor is private.

Parameters

CMsvSession & aMsvSession

CreateNewMessageEntryL(TMsvId, TMsvId &)

IMPORT_C TInt	CreateNewMessageEntryL	(	TMsvId	aFolder,
			TMsvId &	aCreatedId
		)

Parameters

TMsvId aFolder
TMsvId & aCreatedId

DeleteCurrentEntryL()

void

DeleteCurrentEntryL

(

)

[private]

DeleteMM(TMsvId)

IMPORT_C TInt

DeleteMM

(

TMsvId

aMmId

)

Delete a multimedia message.

Parameters

TMsvId aMmId

The index to the MM, which will be deleted

DiskSpaceBelowCriticalLevelL(TInt)

IMPORT_C TInt

DiskSpaceBelowCriticalLevelL

(

TInt

aSize

)

Check if disk space is below critical level when storing data. This is a wrapper function.

Since: 3.0

Parameters

TInt aSize

DoCancel()

void

DoCancel

(

)

[protected, virtual]

From CActive

FinalizeDecodedMML()

void

FinalizeDecodedMML

(

)

[private]

GenerateRecipientsL(TDes &)

void

GenerateRecipientsL

(

TDes &

aDetails

)

[private]

Parameters

TDes & aDetails

GenerateSenderL(TDes &)

void

GenerateSenderL

(

TDes &

aDetails

)

[private]

Parameters

TDes & aDetails

GetNextDataPart(TPtrC8 &, TBool &)

IMPORT_C TInt	GetNextDataPart	(	TPtrC8 &	aDataPart,
			TBool &	aLastDataChunk
		)

Obtain a data part from the supplier. The data is guaranteed to survive until a call is made to ReleaseData() . If the component that is receiving the data cannot receive all data in one chunk, data can be given forward in smaller chunks. The data will will remain in the internal buffer of CodecClient until it has been released by calling ReleaseData() .

Since: S60 v3.1

Parameters

TPtrC8 & aDataPart	Pointer to the data that has been encoded into internal buffer The length of the pointer is set to reflect the amount of data.
TBool & aLastDataChunk	ETrue if this is the last data chunk EFalse if this is not the last data chunk

InitializeChunkedAddingL(TMsvId, TMsvId &, TUint32, TBool)

IMPORT_C void	InitializeChunkedAddingL	(	TMsvId	aFolder,
			TMsvId &	aMessageId,
			TUint32	aFlags,
			TBool	aUnread
		)

Initialize adding a message in chunked mode. An empty invisible message entry is created into the folder specified.

Since: S60 v3.1

Parameters

TMsvId aFolder	The folder where the message will be added
TMsvId & aMessageId	The ID of the message that has been created
TUint32 aFlags	The flags of the MM to be stored in iMtmData1
TBool aUnread	Specifies if the message is unread or not Leaves with KErrArgument if aFolder is invalid or if called in the middle of some other operation Leaves with some system wide error code if something goes wrong.

InitializeChunkedReplacingL(TMsvId, TUint32, TBool)

IMPORT_C void	InitializeChunkedReplacingL	(	TMsvId	aMessageId,
			TUint32	aFlags,
			TBool	aUnread
		)

Initialize replacing a message in chunked mode. The present content of the message entry is deleted. The data is added by calling NextDataPart()

Since: S60 v3.1

Parameters

TMsvId aMessageId	The ID of the message that will be replaced
TUint32 aFlags	The flags of the MM to be stored in iMtmData1
TBool aUnread	Specifies if the message is unread or not Leaves with KErrArgument if aFolder is invalid or if called in the middle of some other operation. Leaves with some system wide error code if something goes wrong.

InitializeChunkedRetrievingL(TMsvId, TMsvId &, TUint32 &, TBool &, TInt &, TRequestStatus &)

IMPORT_C void	InitializeChunkedRetrievingL	(	TMsvId	aMessageId,
			TMsvId &	aFolder,
			TUint32 &	aFlags,
			TBool &	aUnread,
			TInt &	aOverallDataSize,
			TRequestStatus &	aStatus
		)

Initialize retrieving a message in chunked mode. Data will be obtained by repeatedly calling GetNextDataPart() and ReleaseData() . Function encodes the first data part into its internal buffer ready to be fetched by calling GetNextDataPart()

Since: S60 v3.1

Parameters

TMsvId aMessageId	Id of the message to be retrieved
TMsvId & aFolder	The folder where the message is stored
TUint32 & aFlags	The flags of the message, from the iMtmData1
TBool & aUnread	If the message is unread or not
TInt & aOverallDataSize	The total size of the encoded data if the size can be determined. -1 means the size could not be determined, and the return value of GetNextDataPart() function should be used to determine when the last data part has been reached. The buffer will be smaller than the total data size except in the case of small messages that may fit in the buffer in one chunk.
TRequestStatus & aStatus	request status of the calling active object Leaves with some system wide error code or completes with error if something goes wrong. If the function leaves, the caller must not set itself active as it was not set pending and will not be completed.

MoveMML(TMsvId, TMsvId, TRequestStatus &)

IMPORT_C void	MoveMML	(	TMsvId	aMmId,
			TMsvId	aParentId,
			TRequestStatus &	aStatus
		)

A multimedia message is moved from a standard folder to another. Moving to outbox is not allowed.

Since: 3.0

Parameters

TMsvId aMmId	the id to the moved MM
TMsvId aParentId	New folder
TRequestStatus & aStatus

NewL(CMsvSession &)

IMPORT_C CMmsCodecClient *

NewL

(

CMsvSession &

aMsvSession

)

[static]

Two-phased constructor.

Parameters

CMsvSession & aMsvSession

Message Server Session handle

NextDataPart(TPtrC8 &, TBool)

IMPORT_C TInt	NextDataPart	(	TPtrC8 &	aDataPart,
			TBool	aLastDataChunk
		)

Gives the next data part to be decoded. Decoding is synchronous. When the code returns, data can be released. MMS Decode may not be able to handle incomplete headers. MMS Codec Client will take care of buffering the incoming data and saving possible uncoded data in a flat buffer the same way CMmsTransaction does. The data should be provided in chunks that are small enough to be copied to an internal buffer without fear of running out of memory. HTTP stack provides data in chunks that are less than 10 kB. A similar size would be recommended but there is no absolute requirement as to the size of the data chunk. A compromise between performance and memory consumption may be used to determine an appropriate buffer size.

Since: S60 v3.1

Parameters

TPtrC8 & aDataPart	the data to be decoded.
TBool aLastDataChunk

ParentOutbox(TMsvId)

TBool

ParentOutbox

(

TMsvId

aMmId

)

[private]

Parameters

TMsvId aMmId

ReleaseData()

IMPORT_C TInt

ReleaseData

(

)

Release the current data part being held at the data supplier. This call indicates to the supplier that the part is no longer needed, and another one can be provided. When this funtion is called, the next data part will be encoded into the buffer. When this function returns, a new data part can be fetched with GetNextDataPart. This function must always be called after the data obtained by GetNextDataPart() call has been processed. This function must also be called after last data chunk has been processed so that the state of the data supplier can be reset.

Since: S60 v3.1

ReleaseRetrievedEntry()

void

ReleaseRetrievedEntry

(

)

[private]

ReplaceMML(TMsvId &, CBufFlat &, TUint32, TBool, TRequestStatus &)

IMPORT_C void	ReplaceMML	(	TMsvId &	aMmId,
			CBufFlat &	aMm,
			TUint32	aFlags,
			TBool	aUnread,
			TRequestStatus &	aStatus
		)

A multimedia message is replaced. First the attachments of the original message is destroyed. Then the new message is stored to the same entry. Flags are set as defined. If the message is in the Outbox, it is not allowed to be replaced.

Parameters

TMsvId & aMmId	the index to the replaceable MM
CBufFlat & aMm	The new MMS
TUint32 aFlags	the flags of the MM, which go to iMtmData1
TBool aUnread	if the MM is unread or not
TRequestStatus & aStatus	request status of the calling active object

ResetChunkedMode()

void

ResetChunkedMode

(

)

[private]

RetrieveFlags(TMsvEntry, TUint32 &, TBool &)

void	RetrieveFlags	(	TMsvEntry	aEntry,
			TUint32 &	aFlags,
			TBool &	aUnread
		)	[private]

Parameters

TMsvEntry aEntry
TUint32 & aFlags
TBool & aUnread

RetrieveMML(TMsvId, CBufFlat &, TMsvId &, TUint32 &, TBool &, TRequestStatus &)

IMPORT_C void	RetrieveMML	(	TMsvId	aMmId,
			CBufFlat &	aMM,
			TMsvId &	aFolder,
			TUint32 &	aFlags,
			TBool &	aUnread,
			TRequestStatus &	aStatus
		)

Retrieves a multimedia message. This function provides an MM in the binary format, the folder where the MM is stored and its flags.

Parameters

TMsvId aMmId	Index to the MM, which will be retrieved
CBufFlat & aMM
TMsvId & aFolder	The folder, in which the message is stored.
TUint32 & aFlags	the flags of the MM, from the iMtmData1
TBool & aUnread	if the MM is unread or not
TRequestStatus & aStatus	request status of the calling active object

RunError(TInt)

TInt

RunError

(

TInt

aError

)

[protected, virtual]

From CActive .

Parameters

TInt aError

RunL()

void

RunL

(

)

[protected, virtual]

From CActive .

SendMML(TMsvId, TRequestStatus &)

IMPORT_C CMsvOperation *	SendMML	(	TMsvId	aMmId,
			TRequestStatus &	aStatus
		)

Sends the specified MM.The message is moved to the Outbox before sending. The caller of the method should not delete CMsvOperation , which is returned from the function until aStatus has completed. If CMsvOperation is destroyed too early, the sending is canceled.