Class CMsvFindOperation

class CMsvFindOperation : public CMsvOperation;

Description

Encapsulates a text search operation.

The class offers an interface for locating messages which contain specified text. Messages may contain data created for, or received from, any of the transport protocols that are supported by the Messaging Architecture (e.g. Email, FAX and SMS).

Clients create a new instance for each search operation to be performed. They are also responsible for destroying the instance once a search operation is complete.

Clients can derive from this class, typically to implement their own version of the function CMsvFindOperation::IsValid(const TMsvEntry &)const.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

• CMsvOperation - Defines an interface for use by objects which control asynchronous commands in t...

• CMsvFindOperation - Encapsulates a text search operation.

Members

Defined in CMsvFindOperation:

• CMsvFindOperation(CMsvSession &,const TDesC &,TMsvPartList,TRequestStatus &)Constructor, specifying search parameters.
• ConstructFindInChildrenL(TMsvId)Second phase constructor, for constructing a search of an entry and of all its c...
• ConstructFindInSelectionL(const CMsvEntrySelection &)Second phase constructor, for constructing a search of a specified selection of ...
• DoCancel()Implements cancellation of an outstanding request.
• FinalProgress()Returns progress information after the search operation is complete.
• FindInChildrenL(CMsvSession &,const TDesC &,TMsvId,TMsvPartList,TRequestStatus &)Creates a new search operation to search for text within a specified root, folde...
• FindInSelectionL(CMsvSession &,const TDesC &,const CMsvEntrySelection &,TMsvPartList,TRequestStatus &)Creates a new search operation to search for text within a specified selection o...
• GetFindResult()constReturns the result of the search operation.
• IsValid(const TMsvEntry &)constDetermines whether a message is to be included in the text search operation.
• ProgressL()Returns progress information.
• RunL()Handles an active object's request completion event.
• ~CMsvFindOperation()Destructor.

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from CMsvOperation:

• CMsvOperation(CMsvSession &,TInt,TRequestStatus &)Constructor. This is called by MTM implementers from the derived class construct...
• Extension_(TUint,TAny *&,TAny *)The extension method provides a polymorphic behaviour to call the correct System...
• Id()constGets the operation ID.
• Mtm()constGets the UID of the MTM associated with the operation.
• Service()constGets the ID of the service that is associated with this operation.
• SystemProgress(TMsvSystemProgress &)This call leads to calling CMsvOperation::SystemProgress(TMsvSystemProgress &...
• iMsvSessionMessage Server session used by object. This is set by the constructor.
• iMtmThe UID of the MTM associated with the operation.
• iObserverRequestStatusRequest status of the operation observer.
• iServiceThe ID of the service that is associated with this operation.

IMPORT_C ~CMsvFindOperation();

Description

Destructor.

protected: IMPORT_C CMsvFindOperation(CMsvSession &aSession, const TDesC &aTextToFind, TMsvPartList aPartList, TRequestStatus &aObserverRequestStatus);

Description

Constructor, specifying search parameters.

Parameters

CMsvSession &aSession An open session with the Message Server const TDesC16 &aTextToFind The text to be found. The length of the text to be found must not be greater than KMsvMaxFindTextLength. TMsvPartList aPartList The parts of the messages which are to be searched. TRequestStatus &aObserverRequestStatus Request status of an observer to signal when the search is complete.

Panic codes

MSGS 306 aTextToFind is longer than KMsvMaxFindTextLength (debug builds only). In release builds, a USER 11 panic will occur.

IMPORT_C static CMsvFindOperation* FindInChildrenL(CMsvSession &aSession, const TDesC &aTextToFind, TMsvId aParentId, TMsvPartList aPartList, TRequestStatus &aObserverRequestStatus);

Description

Creates a new search operation to search for text within a specified root, folder or service.

Searching for messages is done recursively through all child services and folders. All messages found are searched for text.

Parameters

CMsvSession &aSession An open session with the Message Server. const TDesC16 &aTextToFind The text to be found. The length of the text to be found must not be greater than KMsvMaxFindTextLength, otherwise the function raises a MSGS 306 panic. TMsvId aParentId The entry Id of the root, a folder or a service. If this is the Id of the root entry, then all messages stored in the message store on the Symbian OS phone are searched. The function leaves with the KErrArgument code if this is neither the entry Id of the root, nor a folder nor a service. TMsvPartList aPartList The parts of the messages which are to be searched. TRequestStatus &aObserverRequestStatus The request status object. This is set when the search operation is complete. The is set to: KErrNone, if the search operation completes successfully.

Return value

CMsvFindOperation * Pointer to the new search operation object.

IMPORT_C static CMsvFindOperation* FindInSelectionL(CMsvSession &aSession, const TDesC &aTextToFind, const CMsvEntrySelection &aSelection, TMsvPartList aPartList, TRequestStatus &aObserverRequestStatus);

Description

Creates a new search operation to search for text within a specified selection of messages.

The function leaves with the KErrArgument code if the first entry in the selection is not recognised as a message.

Parameters

CMsvSession &aSession An open session with the Message Server. const TDesC16 &aTextToFind The text to be found. The length of the text to be found must not be greater than KMsvMaxFindTextLength, otherwise the function raises a MSGS 306 panic. const CMsvEntrySelection &aSelection A selection of messages to search. The function raises a MSGS 258 panic if the selection is empty (i.e. there are zero messages in the selection). TMsvPartList aPartList The parts of the messages which are to be searched. TRequestStatus &aObserverRequestStatus The request status object. This is set when the search operation is complete. The is set to: KErrNone, if the search operation completes successfully. KErrArgument, if any of the entries in the selection, apart from the first, cannot be recognised as a message.

Return value

CMsvFindOperation * Pointer to the new search operation object.

IMPORT_C virtual const TDesC8& ProgressL();

Description

Returns progress information.

Progress information supplies sufficient data to drive a progress gauge for the text search operation and also identifies the message currently being searched. It does not provide any information about the search progress within a message.

Return value

const TDesC8 & A reference to a descriptor holding progress information. Progress information is encapsulated by a TMsvFindOperationProgress type object and this is returned as a package buffer, a TPckgBuf object.

IMPORT_C virtual const TDesC8& FinalProgress();

Description

Returns progress information after the search operation is complete.

The function returns the same information as CMsvFindOperation::ProgressL() but can only be called after the search operation is complete. The function raises a MSGS 285 panic if it is called while the search operation is still in progress.

Return value

const TDesC8 & A reference to a descriptor holding progress information. Progress information is encapsulated by a TMsvFindOperationProgress type object and this is returned as a package buffer, a TPckgBuf object

inline const CMsvFindResultSelection& GetFindResult() const;

Description

Returns the result of the search operation.

If the search operation is still in progress, then the results returned are those that have been found at the time of this call.

Return value

const CMsvFindResultSelection & A reference to the search operation results.

protected: IMPORT_C void ConstructFindInChildrenL(TMsvId aId);

Description

Second phase constructor, for constructing a search of an entry and of all its children.

Parameters

TMsvId aId The entry Id of the root, folder or service to search

protected: IMPORT_C void ConstructFindInSelectionL(const CMsvEntrySelection &aSelection);

Description

Second phase constructor, for constructing a search of a specified selection of messages.

Parameters

const CMsvEntrySelection &aSelection A selection of messages to search.

Panic codes

MSGS 258 The selection is empty

private: IMPORT_C virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's CActive::Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

CMsvFindOperation::DoCancel() must not wait for event completion; this is handled by CActive::Cancel().

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

private: IMPORT_C virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's CMsvFindOperation::RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

CMsvFindOperation::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CActive::RunError(TInt) to handle the leave.

Note that once the active scheduler's Start() function has been called, all user code is run under one of the program's active object's CMsvFindOperation::RunL() or CActive::RunError(TInt) functions.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• CActiveScheduler::WaitForAnyRequest()Wait for an asynchronous request to complete.

private: virtual TBool IsValid(const TMsvEntry &aEntry) const;

Description

Determines whether a message is to be included in the text search operation.

The function acts as a filter that decides whether a message should be included in the text search operation. The function is called before the message is searched.

The default implementation always returns true.

Clients can provide their own implementation.

Note: Messages which are not included in the search are still included in the count of entries completed.

Parameters

const TMsvEntry &aEntry The entry Id for a message.

Return value

TBool True, if the message is to be searched. False if the message is not to be searched.