1 epos_cposlmtextcriteria.h

     1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CPosLmTextCriteria class

    15 *

    16 */

    17 

    18 

    19 #ifndef CPOSLMTEXTCRITERIA_H

    20 #define CPOSLMTEXTCRITERIA_H

    21 

    22 #include <e32base.h>

    23 #include <LbsFields.h>

    24 #include <EPos_CPosLandmark.h>

    25 #include "EPos_CPosLmSearchCriteria.h"

    26 

    27 const TInt KPosLmMaxSearchStringLength = 255;

    28 

    29 /**

    30 *  Criterion for searching for landmarks which contain a certain text.

    31 *

    32 *  The search is defined by providing a text to search for and the position

    33 *  fields and text attributes to search.

    34 *

    35 *  If no attributes are specified for the search, all text attributes in the

    36 *  landmarks are searched. If no position fields are specified, then all

    37 *  fields are searched.

    38 *

    39 *  If this criterion is passed to

    40 *  @ref CPosLandmarkSearch::StartLandmarkSearchL, only landmarks which contain

    41 *  the specified text are returned.

    42 *

    43 *  Wild-card characters are supported.

    44 *

    45 *  This criterion is only valid when searching for landmarks, i.e. if it

    46 *  is passed to @p CPosLandmarkSearch::StartCategorySearchL, the function

    47 *  will fail with error code @p KErrArgument.

    48 *

    49 *  @lib eposlmsearchlib.lib

    50 *  @since S60 3.0

    51 */

    52 class CPosLmTextCriteria : public CPosLmSearchCriteria

    53     {

    54     public:

    55 

    56         /**

    57         * Two-phased constructor.

    58         * @returns A new instance of this class.

    59         */

    60         IMPORT_C static CPosLmTextCriteria* NewLC();

    61 

    62         /**

    63         * Destructor.

    64         */

    65         virtual ~CPosLmTextCriteria();

    66 

    67     public:

    68 

    69         /**

    70         * Retrieves the text to search for.

    71         *

    72         * @return The text to search for.

    73         */

    74         IMPORT_C TPtrC Text() const;

    75 

    76         /**

    77         * Sets the search string.

    78         *

    79         * A non-empty text string must be set, otherwise

    80         * @ref CPosLandmarkSearch::StartLandmarkSearchL will leave with error

    81         * code @p KErrArgument.

    82         *

    83         * The search is case insensitive.

    84         *

    85         * Wild-card characters "?" and "*" are supported in the search string.

    86         * "?" matches a single occurrence of any character and "*" matches

    87         * zero or more consecutive occurrences of any characters.

    88         *

    89         * A landmark matches the criterion if specified text is found anywhere

    90         * in selected attributes or position fields.

    91         *

    92         * @param aText The text to search for.

    93         *

    94         * @leave KErrArgument The search string is longer than @p KPosLmMaxSearchStringLength.

    95         */

    96         IMPORT_C void SetTextL( const TDesC& aText );

    97 

    98         /**

    99         * Retrieves the landmark attributes which should be searched.

   100         *

   101         * This function returns a bitmap of landmark attributes. The landmark

   102         * attributes are defined by @p CPosLandmark::_TAttributes. It is only

   103         * possible to search the @p ELandmarkName and @p EDescription

   104         * attributes.

   105         *

   106         * @return A bitmap indicating which landmark attributes should be

   107         *   searched.

   108         */

   109         IMPORT_C CPosLandmark::TAttributes AttributesToSearch() const;

   110 

   111         /**

   112         * Sets which landmark attributes to search.

   113         *

   114         * The client passes a bitmap of the landmark attributes to search. It

   115         * is only possible to search the @p ELandmarkName and @p EDescription

   116         * attributes.

   117         *

   118         * @param aAttributes A bitmap indicating which landmark attributes

   119         *   should be searched.

   120         *

   121         * @panic "Landmarks Client"-EPosInvalidLandmarkAttribute

   122         *   Unsupported attribute is passed.

   123         */

   124         IMPORT_C void SetAttributesToSearch(

   125             CPosLandmark::TAttributes aAttributes

   126         );

   127 

   128         /**

   129         * Retrieves a list of the position fields to search.

   130         *

   131         * @param[out] aFieldArray On return, contains a list of the position fields

   132         *   which are used in a search. If no position fields have been set,

   133         *   the array is empty. Position fields are identified by values defined

   134         *   in @p TPositionFieldId.

   135         */

   136         IMPORT_C void GetPositionFieldsToSearchL(

   137             RArray<TUint>& aFieldArray

   138         ) const;

   139 

   140         /**

   141         * Sets the position fields to search.

   142         *

   143         * Any previously set position fields are cleared by this call.

   144         *

   145         * @param[in] aFieldArray A list of the position fields to search.

   146         *   Position fields are identified by values defined in

   147         *   @p TPositionFieldId.

   148         */

   149         IMPORT_C void SetPositionFieldsToSearchL(

   150             const RArray<TUint>&  aFieldArray

   151         );

   152 

   153         /**

   154         * Clears the position fields list used in a search.

   155         */

   156         IMPORT_C void ClearPositionFieldsToSearch();

   157 

   158     private:

   159 

   160         CPosLmTextCriteria();

   161 

   162         void ConstructL();

   163 

   164         // Prohibit copy constructor

   165         CPosLmTextCriteria( const CPosLmTextCriteria& );

   166         // Prohibit assigment operator

   167         CPosLmTextCriteria& operator= ( const CPosLmTextCriteria& );

   168 

   169     private:

   170 

   171         HBufC*                      iText;

   172         RArray<TUint>               iPositionFieldArray;

   173         CPosLandmark::TAttributes   iAttributes;

   174 

   175     };

   176 

   177 #endif      // CPOSLMTEXTCRITERIA_H

   178 

   179