diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita --- a/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,239 +1,239 @@ - - - - - -Search-Sort -Introduction -

In Symbian OS v9.3 and earlier, when a search or sort query is made by -a client, Message Server searches in the permanent file store (a proprietary -formatted file), and returns the result to the client.

-

From Symbian^3 onwards Message Server operates with the SQL -database to store index entries. With the SQL database implementation the -Message Server makes a query on the SQL index entry table, and returns the -result to the client.

-

The Messaging Middleware module provides an enhanced API for searching -and sorting messages. This API can be used only when the SQL database is used -to store the index entries. The API has the following features:

- -

The following sections include basic information on the search-sort functionality, -which is important to understand before using the search-sort APIs:

- -
Description

The -search-sort functionality is based on the client-server architecture. The -Messaging Middleware module provides an advanced search-sort capability if -the index entries are stored in an SQL database.

The client creates -a search-sort query, and passes it to the Message Server. The Message Server -searches in the search-sort cache to check whether the query is a repetitive -query (a query that was already requested in the past and for which a query -ID is maintained in the search-sort cache) or a new query.

If it is -a repetitive query, the Message Server gets the index entry from the SQL database, -and provides the search result to the client.

If it is a new query, -the Message Server stores the search query in the cache, and passes the query -to the SQL database.

In both the cases, the Message Server gets the -index entry from the SQL database, passes the result to the client, and maintains -the query in the search-sort cache.

The iterative method can be used -for searching and sorting a new or a repetitive search query.

The -following table provides detailed information on the fields supported in the -search-sort operation:

- - - -Operation -Header -Body -TMsvEntry - - - - -

Searching

-

To, cc, bcc, from, subject

-

Body part, whole and partial word (case sensitive and insensitive, -whole word, wildcard)

-

Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

- - -

Searching with explicit sorting

-

To, cc, bcc, from, subject

-

-

 -

Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

- - -

Sorting

-

To, cc, bcc, from, subject

- -

Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

- - - -

Key terms

- -
Iterator
-

An iterator is a method that allows a client to access the search and -sort results sequentially. An iterator is useful when a client does not want -to provide the memory to receive an array of results.

- - -
Search-sort cache
-

Search-sort cache contains frequently requested search-sort queries. -By default, this cache is set to 20 percent of the index entry cache.

For -more information the search-sort cache, see Search-Sort -Cache.

- -
-
Search-sort -API summary

Use the following APIs available in msgs.dll for -searching and sorting messages:

- High level class diagram of new search-sort API - - -
    -

  • CMsvSearchSortOperation

    The CMsvSearchSortOperation class is used in the client application for enhanced search-sort operations -on the message store.

    This class can be used for the following:

      -

    • To run a simple or complex -search-sort request.

      • -

    • To repeat an earlier -search-sort operation by using the queryId.

      • -

    • To receive results either -in one chunk using an array or one after the other using an iterative method.

      The -search-sort results can be received as a list of TMsvId or TMsvEntry objects.
      • -
    • -

  • CMsvSearchSortQuery

    The CMsvSearchSortQuery class -is used in the client application to create a search-sort query. It has an -interface to add or set the query criteria on various message parts.

    This -class provides the following search options:

      -

    • Case sensitive search -(SetCaseSensitiveOption)

      By default this option -is set to false.

      • -

    • Whole word search (SetWholeWord)

      By -default this option is set to false.

      • -

    • Wildcard search (SetWildCardSearch)

      Allow -the use of the asterisk (*) and question mark (?) wildcards. By default this -option is set to false.

      • -

    • Subfolder search (SetSubFolderSearch)

      Include -the entries within the subfolders in the search result. By default this option -is set to false.

      The subfolder option is valid only for a search -query.
      • -

    • Explicit single level -sort (using the TMsvMessagePart aMessagePart parameter -in the CMsvSearchSortQuery::AddSearchOptionL function.

      Sorting -on one particular message part.

      • -

    The CMsvSearchSortQuery class is used with the CMsvSearchSortOperation class -when requesting a new search-sort operation.

    By -default, the search query results are not sorted. To receive a result in a -sorted order, you must send a sort request by using the CMsvSearchSortQuery::AddSortOptionL() function. -Sort options can be used with search options when creating a search-sort query.
    • -

  • TMsvMessagePart

    The TMsvMessagePart is -an enumeration type class that contains all parts of the message, including -index entry and message header. Searching or sorting is done based on the TMsvMessagePart class.

    • -

  • TMsvSearchSortResultType

    The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to -specify if the search and sort results are returned as TMsvId or TMsvEntry.

    • -

  • TMsvRelationOp

    The TMsvRelationOp is -an enumeration type class that is used to provide relational operations between -the search criteria value and the value in the message part of a message.

    For -example, equal to, greater than, greater than or equal to, less than, and -less than or equal to.

    • -

  • TMsvSortOrder

    The TMsvSortOrder is -an enumeration type class that is used to provide the sorting options for -sorting queries. The search or sort results can be sorted in ascending or -descending order.

    • -
-
Advantages

The -following are the advantages of the enhanced search-sort functionality:

    -

  • Search messages by the -following fields:

    Most of the following fields are applicable to -email messages:
      -

    • Sender, recipient list -(cc, to, bcc), subject

      • -

    • Mail size and size range

      • -

    • Date and date range

      • -

    • Message type (SMS, Email, -MMS, and BIO message)

      • -

    • Priority (high, medium, -and low)

      • -

    • Attachment types (linked -attachment and file attachment)

      • -

    • Message status

      For -example, New, Read, Unread, and so on.

      • -
    • -

  • Search messages containing -a specified string in a specified message part.

    • -

  • Search within subfolders -of the parent folder.

    • -

  • Provides combined search -and sort options to the client.

    • -

  • Provides explicit single -level of sorting with implicit sort by data and time.

    • -

  • Allows client to implement -more versatile UI views.

    • -

  • Returns total number -of search-sort count without sending the resultant data. For example, the -number of unread messages in the inbox.

    • -

  • Provides good RAM performance -for repetitive search-sort requests, as the Messaging framework maintains -a search-sort cache for frequently used search-sort requests.

    • -
-
Limitations

The -following are the limitations of the advanced search and sort functionality:

    -

  • The search-sort operation -for a specific value in a specific message part is supported, but searching -for a specific value in all message parts is not supported.

    • -

  • Index entry is migrated -to SQL. The header and body part are yet to be migrated to SQL. So the iterative -method is supported only if the message parts in the index entry are used -in creating the search-sort query.

    • -

  • The following are not -supported in the iterative method because the limitations of SQL:

      -

    • Accessing the next set -of values, that is, next n values (results).

      • -

    • Accessing the previous -value or the previous set of values.

      • -

    • Accessing a random value -or a random set of values.

      • -
    • -

  • Multi level sorting -is not supported.

    • -

  • A search query can use -a maximum of five message parts as search criteria in a combined search.

    • -

  • Sorting on message body -is not supported.

    • -

  • Search-sort operation -cannot be performed on all the message parts present in index entry. The supported -list consists of message parts present in message header, message body and -a partial list of message parts from index entry. See the TMsvMessagePart enumeration -class for the supported message parts.

    • -
- -Search-Sort -Cache -Example code - + + + + + +Search-Sort +Introduction +

In Symbian OS v9.3 and earlier, when a search or sort query is made by +a client, Message Server searches in the permanent file store (a proprietary +formatted file), and returns the result to the client.

+

From Symbian^3 onwards Message Server operates with the SQL +database to store index entries. With the SQL database implementation the +Message Server makes a query on the SQL index entry table, and returns the +result to the client.

+

The Messaging Middleware module provides an enhanced API for searching +and sorting messages. This API can be used only when the SQL database is used +to store the index entries. The API has the following features:

+
    +

  • Combined search (combination +of more than one simple search criteria)

    • +

  • Search based on whole +and partial words

    • +

  • Case sensitive search

    • +

  • Wildcard search

    • +

  • Count of total search +results

    • +

  • Single level sorting +of search results

    • +

  • Iterative mechanism +for clients to access the search and sort results sequentially.

    • +
+

The following sections include basic information on the search-sort functionality, +which is important to understand before using the search-sort APIs:

+
    +

  • Description

    • +

  • Search-sort API summary

    • +

  • Advantages

    • +

  • Limitations

    • +
+
Description

The +search-sort functionality is based on the client-server architecture. The +Messaging Middleware module provides an advanced search-sort capability if +the index entries are stored in an SQL database.

The client creates +a search-sort query, and passes it to the Message Server. The Message Server +searches in the search-sort cache to check whether the query is a repetitive +query (a query that was already requested in the past and for which a query +ID is maintained in the search-sort cache) or a new query.

If it is +a repetitive query, the Message Server gets the index entry from the SQL database, +and provides the search result to the client.

If it is a new query, +the Message Server stores the search query in the cache, and passes the query +to the SQL database.

In both the cases, the Message Server gets the +index entry from the SQL database, passes the result to the client, and maintains +the query in the search-sort cache.

The iterative method can be used +for searching and sorting a new or a repetitive search query.

The +following table provides detailed information on the fields supported in the +search-sort operation:

+ + + +Operation +Header +Body +TMsvEntry + + + + +

Searching

+

To, cc, bcc, from, subject

+

Body part, whole and partial word (case sensitive and insensitive, +whole word, wildcard)

+

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + +

Searching with explicit sorting

+

To, cc, bcc, from, subject

+

-

 +

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + +

Sorting

+

To, cc, bcc, from, subject

+ +

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + + +

Key terms

+ +
Iterator
+

An iterator is a method that allows a client to access the search and +sort results sequentially. An iterator is useful when a client does not want +to provide the memory to receive an array of results.

+ + +
Search-sort cache
+

Search-sort cache contains frequently requested search-sort queries. +By default, this cache is set to 20 percent of the index entry cache.

For +more information the search-sort cache, see Search-Sort +Cache.

+ +
+
Search-sort +API summary

Use the following APIs available in msgs.dll for +searching and sorting messages:

+ High level class diagram of new search-sort API + + +
    +

  • CMsvSearchSortOperation

    The CMsvSearchSortOperation class is used in the client application for enhanced search-sort operations +on the message store.

    This class can be used for the following:

      +

    • To run a simple or complex +search-sort request.

      • +

    • To repeat an earlier +search-sort operation by using the queryId.

      • +

    • To receive results either +in one chunk using an array or one after the other using an iterative method.

      The +search-sort results can be received as a list of TMsvId or TMsvEntry objects.
      • +
    • +

  • CMsvSearchSortQuery

    The CMsvSearchSortQuery class +is used in the client application to create a search-sort query. It has an +interface to add or set the query criteria on various message parts.

    This +class provides the following search options:

      +

    • Case sensitive search +(SetCaseSensitiveOption)

      By default this option +is set to false.

      • +

    • Whole word search (SetWholeWord)

      By +default this option is set to false.

      • +

    • Wildcard search (SetWildCardSearch)

      Allow +the use of the asterisk (*) and question mark (?) wildcards. By default this +option is set to false.

      • +

    • Subfolder search (SetSubFolderSearch)

      Include +the entries within the subfolders in the search result. By default this option +is set to false.

      The subfolder option is valid only for a search +query.
      • +

    • Explicit single level +sort (using the TMsvMessagePart aMessagePart parameter +in the CMsvSearchSortQuery::AddSearchOptionL function.

      Sorting +on one particular message part.

      • +

    The CMsvSearchSortQuery class is used with the CMsvSearchSortOperation class +when requesting a new search-sort operation.

    By +default, the search query results are not sorted. To receive a result in a +sorted order, you must send a sort request by using the CMsvSearchSortQuery::AddSortOptionL() function. +Sort options can be used with search options when creating a search-sort query.
    • +

  • TMsvMessagePart

    The TMsvMessagePart is +an enumeration type class that contains all parts of the message, including +index entry and message header. Searching or sorting is done based on the TMsvMessagePart class.

    • +

  • TMsvSearchSortResultType

    The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to +specify if the search and sort results are returned as TMsvId or TMsvEntry.

    • +

  • TMsvRelationOp

    The TMsvRelationOp is +an enumeration type class that is used to provide relational operations between +the search criteria value and the value in the message part of a message.

    For +example, equal to, greater than, greater than or equal to, less than, and +less than or equal to.

    • +

  • TMsvSortOrder

    The TMsvSortOrder is +an enumeration type class that is used to provide the sorting options for +sorting queries. The search or sort results can be sorted in ascending or +descending order.

    • +
+
Advantages

The +following are the advantages of the enhanced search-sort functionality:

    +

  • Search messages by the +following fields:

    Most of the following fields are applicable to +email messages:
      +

    • Sender, recipient list +(cc, to, bcc), subject

      • +

    • Mail size and size range

      • +

    • Date and date range

      • +

    • Message type (SMS, Email, +MMS, and BIO message)

      • +

    • Priority (high, medium, +and low)

      • +

    • Attachment types (linked +attachment and file attachment)

      • +

    • Message status

      For +example, New, Read, Unread, and so on.

      • +
    • +

  • Search messages containing +a specified string in a specified message part.

    • +

  • Search within subfolders +of the parent folder.

    • +

  • Provides combined search +and sort options to the client.

    • +

  • Provides explicit single +level of sorting with implicit sort by data and time.

    • +

  • Allows client to implement +more versatile UI views.

    • +

  • Returns total number +of search-sort count without sending the resultant data. For example, the +number of unread messages in the inbox.

    • +

  • Provides good RAM performance +for repetitive search-sort requests, as the Messaging framework maintains +a search-sort cache for frequently used search-sort requests.

    • +
+
Limitations

The +following are the limitations of the advanced search and sort functionality:

    +

  • The search-sort operation +for a specific value in a specific message part is supported, but searching +for a specific value in all message parts is not supported.

    • +

  • Index entry is migrated +to SQL. The header and body part are yet to be migrated to SQL. So the iterative +method is supported only if the message parts in the index entry are used +in creating the search-sort query.

    • +

  • The following are not +supported in the iterative method because the limitations of SQL:

      +

    • Accessing the next set +of values, that is, next n values (results).

      • +

    • Accessing the previous +value or the previous set of values.

      • +

    • Accessing a random value +or a random set of values.

      • +
    • +

  • Multi level sorting +is not supported.

    • +

  • A search query can use +a maximum of five message parts as search criteria in a combined search.

    • +

  • Sorting on message body +is not supported.

    • +

  • Search-sort operation +cannot be performed on all the message parts present in index entry. The supported +list consists of message parts present in message header, message body and +a partial list of message parts from index entry. See the TMsvMessagePart enumeration +class for the supported message parts.

    • +
+ +Search-Sort +Cache +Example code + \ No newline at end of file