1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 2013-2014 Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_EC_QUERY_H_ 14 #define NN_EC_QUERY_H_ 15 16 #include <nn/ec/ec_Types.h> 17 18 namespace nn { namespace ec { 19 20 //! @addtogroup nn_ec_class 21 //! @{ 22 23 /*! 24 @brief Class for handling a query expression. 25 26 The following operators can be used in a query expression. 27 28 @li "==" 29 @li "!=" 30 @li "<" 31 @li "<=" 32 @li ">" 33 @li ">=" 34 @li "LIKE" 35 */ 36 class Expression : public RootObject 37 { 38 public: 39 /*! 40 @brief Instantiates the object. 41 42 @param[in] expression Specifies the query expression. 43 */ 44 Expression(const Expression& expression); 45 46 /*! 47 @brief Constructs the object with an integer attribute value. 48 49 The LIKE operator cannot be used. 50 51 @param[in] pName Specifies the attribute name. 52 @param[in] pOperator Specifies the operator. 53 @param[in] value Specifies the attribute value. 54 */ 55 Expression(const char* pName, const char* pOperator, s32 value); 56 57 /*! 58 @brief Constructs the object with a string attribute value. 59 60 The following fuzzy searches are possible when the LIKE operator is used. 61 62 @li Exact match. @n 63 Specify the attribute value as "$...$". 64 @li Substring match. @n 65 Specify the attribute value as "*...*". 66 @li Begins with. @n 67 Specify the attribute value as "$...*". 68 @li Ends with. @n 69 Specify the attribute value as "*...$". 70 71 @param[in] pName Specifies the attribute name. 72 @param[in] pOperator Specifies the operator. 73 @param[in] pValue Specifies the attribute value. @n 74 The value must be UTF-8 encoded. 75 */ 76 Expression(const char* pName, const char* pOperator, const char* pValue); 77 78 public: 79 // internal: 80 const char* GetName() const; 81 // internal: 82 const char* GetOperator() const; 83 // internal: 84 s32 GetIntegerValue() const; 85 // internal: 86 const char* GetStringValue() const; 87 88 private: 89 // 90 const char* m_pName; 91 // 92 const char* m_pOperator; 93 // 94 s32 m_integer; 95 // 96 const char* m_pString; 97 }; 98 99 /*! 100 @brief Class for handling an attribute filter. 101 102 The following values can be specified in an attribute filter. 103 104 @li "(" 105 @li ")" 106 @li "AND" 107 @li "OR" 108 @li @ref Expression 109 */ 110 class AttributeFilter : public RootObject 111 { 112 public: 113 /*! 114 @brief This constructor is used for specifying a value other than a query expression. 115 116 @param[in] pNonExpression Specifies a non-query parameter. 117 */ 118 AttributeFilter(const char* pNonExpression = NULL); 119 120 /*! 121 @brief This constructor is used for specifying a query expression. 122 123 @param[in] expression Specifies the query expression. 124 */ 125 AttributeFilter(const Expression& expression); 126 127 public: 128 // internal: 129 const char* GetNonExpression() const; 130 // internal: 131 const Expression* GetExpression() const; 132 133 private: 134 // 135 const char* m_pNonExpression; 136 // 137 Expression m_expression; 138 }; 139 140 /*! 141 @brief Class for handling a query. 142 143 @see <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712107">Programming Manual</a> 144 */ 145 class Query : public RootObject, private NonCopyable<Query> 146 { 147 public: 148 NN_EC_DECLARE_ACCESSOR; 149 NN_EC_DECLARE_IMPL; 150 151 public: 152 /*! 153 @brief Specifies the maximum length of the filter string. 154 */ 155 static const size_t FILTER_LENGTH_MAX = 2048; 156 157 /*! 158 @brief Specifies the character that represents the beginning or end in a LIKE statement. 159 */ 160 static const char END_CHARACTER = '$'; 161 /*! 162 @brief Specifies the character that represents a wildcard in a LIKE statement. 163 */ 164 static const char WILDCARD_CHARACTER = '*'; 165 166 /*! 167 @brief Specifies the maximum number of attributes that can be specified in a query. 168 */ 169 static const u32 ATTRIBUTE_NUM_MAX = 20; 170 /*! 171 @brief Specifies the maximum number of expressions that can be specified in a query. 172 */ 173 static const u32 EXPRESSION_NUM_MAX = 8; 174 /*! 175 @brief Specifies the maximum depth of nested brackets in a query. 176 */ 177 static const u32 BRACKET_NESTING_DEPTH_MAX = 4; 178 179 public: 180 /*! 181 @brief Instantiates the object. 182 */ 183 Query(); 184 185 /*! 186 @brief Destroys the object. 187 */ 188 ~Query(); 189 190 /*! 191 @brief Clears the object. 192 193 When this function is called, internally allocated memory is released. 194 */ 195 void Clear(); 196 197 /*! 198 @brief Selects the attributes to retrieve. 199 200 To clear the retrieved attributes, set the number of attribute names to 0. 201 202 @param[in] ppNames Specifies a list of attribute names to retrieve. 203 @param[in] num Specifies the number of attribute names to retrieve. 204 205 @return The result of processing. 206 207 @retval Result::IsSuccess Indicates success. 208 @retval ResultInvalidArgument Indicates that an argument is invalid. 209 @retval ResultOutOfMemory Insufficient memory. 210 */ 211 nn::Result Select(const char** ppNames, u32 num); 212 213 /*! 214 @brief Specifies the attribute-based filtering conditions. 215 216 To clear the filters, set the number of attribute filters to 0. 217 218 @param[in] pFilters Specifies a list of attribute filters. 219 @param[in] num Specifies the number of attribute filters. 220 221 @return The result of processing. 222 223 @retval Result::IsSuccess Indicates success. 224 @retval ResultInvalidArgument Indicates that an argument is invalid. 225 @retval ResultOutOfMemory Insufficient memory. 226 */ 227 nn::Result Where(const AttributeFilter* pFilters, u32 num); 228 229 /*! 230 @brief Sets the sorting method. 231 232 To clear the sorting method, set the attribute name to <tt>NULL</tt>. @n 233 By default, the data is sorted by item code. 234 235 @param[in] pName Specifies the attribute name to sort on. @n 236 In addition to user-defined attributes, the following system attributes are available. 237 @li sys.ItemName@n 238 Sort by the sort name of the item set in IMAS. @n 239 Set the sort type to ascending when sorting by name. 240 @li sys.ReleaseDate@n 241 Sort by the <b>New Since</b> value of the item. @n 242 Set the sort type to descending when sorting by newest arrival. 243 @li sys.Popularity@n 244 Sort by item popularity (number of downloads). @n 245 Set the sort type to descending when sorting by popularity. 246 @param[in] pOrder Specifies the sort type. @n 247 Specify <tt>ASC</tt> for ascending and <tt>DESC</tt> for descending. @n 248 @param[in] pDataType Specifies the data type of the attribute to sort by. @n 249 Specify <tt>STRING</tt> for a string or <tt>INTEGER</tt> for a number. @n 250 Note that the data type is ignored when sorting on a system attribute. 251 252 @return The result of processing. 253 254 @retval Result::IsSuccess Indicates success. 255 @retval ResultInvalidArgument Indicates that an argument is invalid. 256 @retval ResultOutOfMemory Insufficient memory. 257 */ 258 nn::Result OrderBy(const char* pName, const char* pOrder = "DESC", const char* pDataType = "STRING"); 259 260 /*! 261 @brief Sets the sales status filter. 262 263 Specify <tt>@ref SALES_STATUS_FILTER_ONSALE</tt> to only search for items that are currently on sale. @n 264 The filter defaults to <tt>@ref SALES_STATUS_FILTER_ONSALE</tt>. 265 266 Specify <tt>@ref SALES_STATUS_FILTER_ALL</tt> to include items that are no longer on sale or are yet to go on sale. 267 268 @param[in] filter Specifies the sales status filter. 269 270 @return The result of processing. 271 272 @retval Result::IsSuccess Indicates success. 273 @retval ResultInvalidArgument Indicates that an argument is invalid. 274 @retval ResultOutOfMemory Insufficient memory. 275 */ 276 nn::Result SetSalesStatusFilter(SalesStatusFilter filter); 277 278 public: 279 // internal: 280 bool ConvertRequest(char* pBuffer, size_t size, u32 flags) const; 281 282 private: 283 // 284 NN_EC_IMPL; 285 }; 286 287 //! @} 288 289 }} // namespace nn::ec 290 291 #endif // NN_EC_QUERY_H_ 292