Class CMsvFindOperation

CMsvFindOperation

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 IsValid().

Derivation

CActive The core class of the active object abstraction CBase Base class for all classes to be instantiated on the heap CMsvFindOperation Encapsulates a text search operation CMsvOperation Defines an interface for use by objects which control asynchronous commands in the messaging system

Defined in CMsvFindOperation:
FinalProgress(), FindInChildrenL(), FindInSelectionL(), GetFindResult(), IsValid(), ProgressL()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
operator new()

Inherited from CMsvOperation:
Id(), Mtm(), Service(), iMsvSession, iMtm, iObserverRequestStatus, iService

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 TDesC& 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.

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 TDesC& 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 EPOC device 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.

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.

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<TMsvFindOperationProgress> object.

const TDesC8& FinalProgress();

Description

Returns progress information after the search operation is complete.

The function returns the same information as 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<TMsvFindOperationProgress> object

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.

Notes

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.