EPOC   SDK Home Glossary Indexes Previous Next Up

CSendAs class


Contents


CSendAs class — High-level message sending

Section Contents


Overview

Compatibility

The class is new in ER5. Applications built using this class will not run on a device with an earlier version of EPOC.

Derivation

CBase

Abstract: CBase behaviour

CActive

Active object abstraction

MMsvSendAsObserver

Abstract class providing the interface for CSendAs to call back a client with further information or requests

Defined in

sendas.h

Link against

send.lib

Description

The CSendAs class is the main encapsulation of the Send-As functionality provided by the EPOC Messaging Architecture. It allows applications simply to package data into outgoing messages without using directly the MTM interfaces. For an overview, see Send As interface.

The class is failure-safe in that if it gets deleted before the client application commits the message, the message is abandoned rather than saved in a potentially indeterminate state, which could later cause problems in the Message Server.

If the MTM requires the data to be rendered (i.e. printed), then, when saving the message, the CSendAs class calls back to the application using the mixin observer, and give the UID of the printer driver to use and the filename the printer should produce.

Incorrect use of this class can cause panics: see SEND panics.


Constructors and destructors


NewL() — Allocate and construct

static CSendAs* NewL(MSendAsObserver& aObserver);

Description

This function should be called to create a Send-As object. It returns a pointer to an instance of a CSendAs object. The Send-As object creates a session against the Message Server and can access the client-side MTM registry. The call returns immediately since any initialisation occurs asynchronously.

Arguments

MSendAsObserver& aObserver

An abstract interface implemented by the client. MTM capability queries may call back this interface

Return value

CSendAs*

New session object if successful


~CSendAs() — Destructor

~CSendAs();

Description

Class destructor. Any current message is abandoned.


Selection of MTMs and services


AvailableMtms() — Get array of capable MTMs

const CDesCArray& AvailableMtms() const

Description

The client calls this function to obtain the array of MTMs that satisfy the current capability requirements. The array could change after every call to AddRequiredCapabilityL() and ResetCapabilitiesL(). The array never contains MTMs that do not have the capability to send messages.

Return value

CDesCArray&

The array of the human-readable names of the MTMs that satisfy the current required capabilities


AddMtmCapabilityL() — Add capability requirement

void AddMtmCapabilityL(TUid aCapabilityId, TBool aResponseExpected=EFalse)

Description

The client calls this function to add a capability requirement. For details of capabilities, see Capability constants.

All MTMs that do not have this capability are removed from the current array of available MTMs, initialised by AvailableMtms(). This allows the client to filter out any unsuitable MTMs before presenting a list to the user. A client can make repeated calls to AvailableMtms() to specify different criteria.

Some clients may wish to perform additional checking of a capability response, which they can do by setting aResponseExpected to ETrue. This causes the function to call back the client’s MSendAsObserver::CapabilityOK() function, which can evaluates the capability further. For example, if the KUidMtmQueryMaxBodySize capability (maximum message body size) is specified, and aResponseExpected is ETrue, the function calls back MSendAsObserver::CapabilityOK() with the maximum message body size. That function can then check if the maximum size is large enough — returning ETrue if it is. AddMtmCapabilityL() then checks this return value: if it is not ETrue, then the MTM is removed from the available MTM array.

Arguments

TUid aCapabilityId

The UID of the required capability

TBool aResponseExpected=EFalse

Set to ETrue if the capability returns a response that needs to be checked by the client

Leave considerations

The function calls CBaseMtm::QueryCapability() on the available MTMs. It leaves if that function does not return KErrNone or KErrNotSupported. The array of MTM names is unchanged.


ResetCapabilitiesL() — Reset array of MTMs

void ResetCapabilitiesL();

Description

Call this function to cancel all capability requirements. The MTM array then contains all the installed MTMs that can send messages.

Leave considerations

KErrNoMemory

A memory allocation failed. The MTM array is unchanged


SetMtmL() — Set MTM to be used by index

void SetMtmL(TInt aMtmIndex);

Description

Use this function to choose which MTM to use to create the message by referencing the available MTM array.

Arguments

TInt aMtmIndex

The index into the available MTM array indicating which MTM to use to create the message. The function panics if an MTM has not been set.

Leave considerations

If the function leaves, then the MTM array is unchanged and a message cannot be created.

KErrNotFound

The specified MTM was not available

KErrNoMemory

A memory allocation failed


SetMtmL() — Set MTM to be used by UID

void SetMtmL(TUid aMtmUid);

Description

Use this function to choose which MTM to use to create the message by specifying a known MTM UID.

For details of standard MTM UIDs, see MTM type UID constants.

Arguments

TUid aMtmUid

The UID of the MTM to use to create the message

Leave considerations

If the function leaves, then the MTM array is unchanged and a message cannot be created.

KErrNotFound

The specified MTM was not available

KErrNoMemory

A memory allocation failed


AvailableServices() — Get available services

const CDesCArray& AvailableServices() const;

Description

After choosing an MTM, this function can be used to obtain a list of the available services. It panics if an MTM has not been set.

Return value

CDesCArray&

The list of the names of services that can be used by the chosen MTM type


SetService() — Set required service

void SetService(TInt aServiceIndex);

Description

Used to set the service to use for the message. The function panics if the index is out of range or an MTM has not been set.

Arguments

TInt aServiceIndex

The index into the service list for the service to use


Message management


CreateMessageL() — Create message

void CreateMessageL();

Description

An MTM must have been set before calling this function. It panics if an MTM has not been set or a message has already been created.

Leave considerations

If the function leaves, then the internal state of the CSendAs instance is unchanged

KErrNotFound

No suitable service exists, or the MTM is not available

Other leaves

Error propagated from Message Server


AbandonMessageL() — Abandon message

void AbandonMessageL();

Description

Use this function to delete a message in progress and any attachments from the Message Server. If an MTM object has been selected, then it the selection is cancelled. It panics if the message has already been saved.

Leave considerations

KErrNotFound

Message Server could not delete the message


SaveMessageL() — Save message

void SaveMessageL(TBool aMakeVisible=ETrue);

void SaveMessageL(TRequestStatus& aStatus, TBool aMakeVisible=ETrue);

Description

Use this function to commit the current message to the Message Server.

When the CSendAs object is deleted by the client application, it issues an AbandonMessage() call on itself — so to ensure that a message is sent, a client application must invoke this function before closing the Send-As API. It panics if no message has been created.

When the message requires rendering (e.g. fax), some applications might use the asynchronous version.

Arguments

TRequestStatus& aStatus

Asynchronous completion object

TBool aMakeVisible

Determines whether the message should be visible in the Outbox. Defaults to true.

Leave considerations

The function can leave if rendering is required, and either an error occurs in requesting the MTM for the printer to use for rendering, or in MMsvSendAsObserver::RenderImage(). The message is left in the same state as it was before the call.


Recipient management


RecipientList() — Get recipients

const CDesCArray& RecipientList() const;

Description

The client can use this function to obtain a list of recipients after they have been added to the message. It panics if no message has been created

Return value

CDesCArray&

A text array that lists all the recipients that have been added


AddRecipientL() — Add recipient

void AddRecipientL(const TDesC& aRealAddress);

Description

Use this function to add an recipient to the message.

Arguments

const TDesC& aRealAddress

The address of the recipient

Leave considerations

Leaves can be propagated from CBaseMtm::AddAddresseeL(). The recipient is not added to the message.


AddRecipientL() — Add recipient with alias

TInt AddRecipientL(const TDesC& aRealAddress, const TDesC& aAlias);

Description

Use this function to add an recipient to the message. Both the true address and the name or alias are specified (e.g., “an-other@somewhere.co.uk” and “A.N. Other”).

Arguments

const TDesC& aRealAddress

The address of the recipient

const TDesC& aAlias

The name or alias of the recipient rather than the actual destination

Leave considerations

Leaves can be propagated from CBaseMtm::AddAddresseeL(). The recipient is not added to the message.


RemoveRecipient() — Remove recipient

void RemoveRecipient(TInt aIndex);

Description

Use this function to remove a recipient from the message. It panics if no message has been created.

Arguments

TInt aIndex

The index of the recipient array to be removed


Contents management


SetSubjectL() — Set subject

void SetSubjectL(const TDesC& aSubject);

Description

Use this function to set the subject of the current message. It panics if no message has been created.

Arguments

const TDesC& aSubject

Descriptor containing the subject line for the message

Leave considerations

Leaves can be propagated from CBaseMtm::SetSubjectL(). KErrNotSupported indicates that the MTM does not support a subject field.


SetBodyL() — Set body text

void SetBodyL(const CRichText& aMessageBody);

Description

Use this function to define the body of the new message.

The outgoing message may legally be left with an empty body if the client application cannot provide the contents of its document as a CRichText object. Alternatively, the client application may wish to define a default message body, and create an attachment for the document being sent. It panics if no message has been created.

Arguments

const CRichText& aMessageBody

Message body text

Leave considerations

Leaves can be propagated from CRichText::InsertL().


Message validity and capability


ValidateMessage() — Validate message format

TMsvPartList ValidateMessage();

Description

The client application may, if so desired, use this function to check that the message is correctly formatted for the chosen message type. In particular, the client application is able to determine whether the recipient list is valid within the addressing syntax of the message type. Any defective part or parts are identified by the return value.

The call panics if no message has been created.

Return value

TMsvPartList

0: message is valid

Non-zero: bitmask identifying defective part or parts


QueryMessageCapability() — Query MTM message capability

TInt QueryMessageCapability(TUid aCapabilityId, TBool aResponseExpected=EFalse);

Description

Use this function to check that the chosen MTM message supports a capability.

If aResponseExpected is ETrue, then the function call backs the client’s MSendAsObserver::CapabilityOK() that can evaluate the capability further.

Arguments

TUid aCapabilityId

The UID of the capability to check

TBool aResponseExpected=EFalse

ETrue if the capability returns a value that needs to be checked by the client

Return value

KErrNone

The capability is supported

KErrNotSupported

The capability is not supported


Attachment management


CreateAttachmentL() — Create attachment

void CreateAttachmentL(TMsvId& aAttachmentId, TFileName& aDirectory);

Description

This function is used by the client application to create an entry for an attachment in the Message Server index. Once an entry has been created, the client application can save the attachment file in the directory whose location is returned in aDirectory. It panics if no message has been created.

Arguments

TMsvId& aAttachmentId

On return, the Message Server index ID of the attachment

TFileName& aDirectory

On return, the directory in which to save the attachment

Leave considerations

Leaves can be propagated from CMsvEntry::CreateL() and CMsvEntry::SetEntryL(). KErrNotSupported indicates that the MTM does not support attachments. The CSendAs instance’s state is unchanged.


DeleteAttachmentL() — Delete attachment

void DeleteAttachmentL(TMsvId aAttachmentId);

Description

This function is used by the client application to delete an attachment from the message. The attachment directory and any files in it are also deleted. It panics if no message has been created.

Arguments

TMsvId aAttachmentId

Identifies the attachment to be deleted

Leave considerations

Leaves can be propagated from CMsvEntry::DeleteL() . The attachment is not deleted.


Advanced Messaging Architecture access


ClientRegistry() — Client registry access

CClientMtmRegistry& ClientRegistry();

Description

This function has been provided to allow advanced clients to get direct access to the Messaging Architecture’s client registry.

Return value

CClientMtmRegistry&

Client registry object


ClientMtm() — Client MTM access

CBaseMTM& ClientMtm();

Description

This function has been provided to allow advanced clients to get direct access to the class providing protocol-specific messaging functionality (a client MTM).

Return value

CBaseMTM&

Client-side MTM object

EPOC       SDK Home Glossary Indexes Previous Next Up