![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
The class is new in ER5. Applications built using this class will not run on a device with an earlier version of EPOC.
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 |
sendas.h
send.lib
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.
static CSendAs* NewL(MSendAsObserver& aObserver);
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.
MSendAsObserver& aObserver |
An abstract interface implemented by the client. MTM capability queries may call back this interface |
CSendAs* |
New session object if successful |
~CSendAs();
Class destructor. Any current message is abandoned.
const CDesCArray& AvailableMtms() const
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.
CDesCArray& |
The array of the human-readable names of the MTMs that satisfy the current required capabilities |
void AddMtmCapabilityL(TUid aCapabilityId, TBool aResponseExpected=EFalse)
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 clients 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.
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 |
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.
void ResetCapabilitiesL();
Call this function to cancel all capability requirements. The MTM array then contains all the installed MTMs that can send messages.
KErrNoMemory |
A memory allocation failed. The MTM array is unchanged |
void SetMtmL(TInt aMtmIndex);
Use this function to choose which MTM to use to create the message by referencing the available MTM array.
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. |
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 |
void SetMtmL(TUid aMtmUid);
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.
TUid aMtmUid |
The UID of the MTM to use to create the message |
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 |
const CDesCArray& AvailableServices() const;
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.
CDesCArray& |
The list of the names of services that can be used by the chosen MTM type |
void SetService(TInt aServiceIndex);
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.
TInt aServiceIndex |
The index into the service list for the service to use |
void CreateMessageL();
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.
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 |
void AbandonMessageL();
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.
KErrNotFound |
Message Server could not delete the message |
void SaveMessageL(TBool aMakeVisible=ETrue);
void SaveMessageL(TRequestStatus& aStatus, TBool aMakeVisible=ETrue);
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.
TRequestStatus& aStatus |
Asynchronous completion object |
TBool aMakeVisible |
Determines whether the message should be visible in the Outbox. Defaults to true. |
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.
const CDesCArray& RecipientList() const;
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
CDesCArray& |
A text array that lists all the recipients that have been added |
void AddRecipientL(const TDesC& aRealAddress);
Use this function to add an recipient to the message.
const TDesC& aRealAddress |
The address of the recipient |
Leaves can be propagated from CBaseMtm::AddAddresseeL(). The recipient is not added to the message.
TInt AddRecipientL(const TDesC& aRealAddress, const TDesC& aAlias);
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).
const TDesC& aRealAddress |
The address of the recipient |
const TDesC& aAlias |
The name or alias of the recipient rather than the actual destination |
Leaves can be propagated from CBaseMtm::AddAddresseeL(). The recipient is not added to the message.
void RemoveRecipient(TInt aIndex);
Use this function to remove a recipient from the message. It panics if no message has been created.
TInt aIndex |
The index of the recipient array to be removed |
void SetSubjectL(const TDesC& aSubject);
Use this function to set the subject of the current message. It panics if no message has been created.
const TDesC& aSubject |
Descriptor containing the subject line for the message |
Leaves can be propagated from CBaseMtm::SetSubjectL(). KErrNotSupported indicates that the MTM does not support a subject field.
void SetBodyL(const CRichText& aMessageBody);
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.
const CRichText& aMessageBody |
Message body text |
Leaves can be propagated from CRichText::InsertL().
TMsvPartList ValidateMessage();
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.
TMsvPartList |
0: message is valid Non-zero: bitmask identifying defective part or parts |
TInt QueryMessageCapability(TUid aCapabilityId, TBool aResponseExpected=EFalse);
Use this function to check that the chosen MTM message supports a capability.
If aResponseExpected is ETrue, then the function call backs the clients MSendAsObserver::CapabilityOK() that can evaluate the capability further.
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 |
KErrNone |
The capability is supported |
KErrNotSupported |
The capability is not supported |
void CreateAttachmentL(TMsvId& aAttachmentId, TFileName& aDirectory);
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.
TMsvId& aAttachmentId |
On return, the Message Server index ID of the attachment |
TFileName& aDirectory |
On return, the directory in which to save the attachment |
Leaves can be propagated from CMsvEntry::CreateL() and CMsvEntry::SetEntryL(). KErrNotSupported indicates that the MTM does not support attachments. The CSendAs instances state is unchanged.
void DeleteAttachmentL(TMsvId aAttachmentId);
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.
TMsvId aAttachmentId |
Identifies the attachment to be deleted |
Leaves can be propagated from CMsvEntry::DeleteL() . The attachment is not deleted.
CClientMtmRegistry& ClientRegistry();
This function has been provided to allow advanced clients to get direct access to the Messaging Architectures client registry.
CClientMtmRegistry& |
Client registry object |
CBaseMTM& ClientMtm();
This function has been provided to allow advanced clients to get direct access to the class providing protocol-specific messaging functionality (a client MTM).
CBaseMTM& |
Client-side MTM object |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |