/*---------------------------------------------------------------------------*

Copyright (C) Nintendo.  All rights reserved.

These coded instructions, statements, and computer programs contain
proprietary information of Nintendo of America Inc. and/or Nintendo
Company Ltd., and are protected by Federal copyright law.  They may
not be disclosed to third parties or copied or duplicated in any form,
in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

#ifndef NN_EC_QUERY_H_
#define NN_EC_QUERY_H_

#include <nn/ec/ec_Types.h>

namespace nn { namespace ec {

//! @addtogroup  nn_ec_class
//! @{

/*!
@brief  Class for handling a query expression.

The following operators can be used in a query expression.

@li  "=="
@li  "!="
@li  "<"
@li  "<="
@li  ">"
@li  ">="
@li  "LIKE"
*/
class Expression : public RootObject
{
public:
    /*!
@brief  Instantiates an object.

@param[in] expression  Specifies the query expression.
*/
    Expression(const Expression& expression);

    /*!
@brief  Constructs the object with an integer attribute value.

The LIKE operator cannot be used.

@param[in] pName  Specifies the attribute name.
@param[in] pOperator  Specifies the operator.
@param[in] value  Specifies the attribute value.
*/
    Expression(const char* pName, const char* pOperator, s32 value);

    /*!
@brief  Constructs the object with a string attribute value.

The following fuzzy searches are possible when the LIKE operator is used.

@li  Exact match. @n
Specify the attribute value as "$...$".
@li  Substring match. @n
Specify the attribute value as "*...*".
@li  Begins with. @n
Specify the attribute value as "$...*".
@li  Ends with. @n
Specify the attribute value as "*...$".

@param[in] pName  Specifies the attribute name.
@param[in] pOperator  Specifies the operator.
@param[in] pValue  Specifies the attribute value. @n
The value must be UTF-8 encoded.
*/
    Expression(const char* pName, const char* pOperator, const char* pValue);

public:
    // internal:
    const char* GetName() const;
    // internal:
    const char* GetOperator() const;
    // internal:
    s32 GetIntegerValue() const;
    // internal:
    const char* GetStringValue() const;

private:
    // 
    const char* m_pName;
    // 
    const char* m_pOperator;
    // 
    s32 m_integer;
    // 
    const char* m_pString;
};

/*!
@brief  Class for handling an attribute filter.

The following values can be specified in an attribute filter.

@li  "("
@li  ")"
@li  "AND"
@li  "OR"
@li  @ref Expression
*/
class AttributeFilter : public RootObject
{
public:
    /*!
@brief  This constructor is used for specifying a value other than a query expression.

@param[in] pNonExpression  Specifies a non-query parameter.
*/
    AttributeFilter(const char* pNonExpression = NULL);

    /*!
@brief  This constructor is used for specifying a query expression.

@param[in] expression  Specifies the query expression.
*/
    AttributeFilter(const Expression& expression);

public:
    // internal:
    const char* GetNonExpression() const;
    // internal:
    const Expression* GetExpression() const;

private:
    // 
    const char* m_pNonExpression;
    // 
    Expression m_expression;
};

/*!
@brief  Class for handling a query.

@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712107">Programming Manual</a>
*/
class Query : public RootObject, private NonCopyable<Query>
{
public:
    NN_EC_DECLARE_ACCESSOR;
    NN_EC_DECLARE_IMPL;

public:
    /*!
@brief  Specifies the maximum length of the filter string.
*/
    static const size_t FILTER_LENGTH_MAX = 2048;

    /*!
@brief  Specifies the character that represents the beginning or end in a LIKE statement.
*/
    static const char END_CHARACTER = '$';
    /*!
@brief  Specifies the character that represents a wildcard in a LIKE statement.
*/
    static const char WILDCARD_CHARACTER = '*';

    /*!
@brief  Specifies the maximum number of attributes that can be specified in a query.
*/
    static const u32 ATTRIBUTE_NUM_MAX = 20;
    /*!
@brief  Specifies the maximum number of expressions that can be specified in a query.
*/
    static const u32 EXPRESSION_NUM_MAX = 8;
    /*!
@brief  Specifies the maximum depth of nested brackets in a query.
*/
    static const u32 BRACKET_NESTING_DEPTH_MAX = 4;

public:
    /*!
@brief  Instantiates an object.
*/
    Query();

    /*!
@brief  Destroys the object.
*/
    ~Query();

    /*!
@brief  Clears the object.

When this function is called, internally allocated memory is released.
*/
    void Clear();

    /*!
@brief  Selects the attributes to retrieve.

To clear the retrieved attributes, set the number of attribute names to 0.

@param[in] ppNames  Specifies a list of attribute names to retrieve.
@param[in] num  Specifies the number of attribute names to retrieve.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval ResultOutOfMemory  Insufficient memory.
*/
    nn::Result Select(const char** ppNames, u32 num);

    /*!
@brief  Specifies the attribute-based filtering conditions.

To clear the filters, set the number of attribute filters to 0.

@param[in] pFilters  Specifies a list of attribute filters.
@param[in] num  Specifies the number of attribute filters.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval ResultOutOfMemory  Insufficient memory.
*/
    nn::Result Where(const AttributeFilter* pFilters, u32 num);

    /*!
@brief  Sets the sorting method.

To clear the sorting method, set the attribute name to <tt>NULL</tt>. @n
By default, the data is sorted by item code.

@param[in] pName  Specifies the attribute name to sort on. @n
In addition to user-defined attributes, the following system attributes are available.
@li  sys.ItemName@n
Sort by the sort name of the item set in IMAS. @n
Set the sort type to ascending when sorting by name.
@li  sys.ReleaseDate@n
Sort by the <b>New Since</b> value of the item. @n
Set the sort type to descending when sorting by newest arrival.
@li  sys.Popularity@n
Sort by item popularity (number of downloads). @n
Set the sort type to descending when sorting by popularity.
@param[in] pOrder  Specifies the sort type. @n
Specify <tt>ASC</tt> for ascending and <tt>DESC</tt> for descending. @n
@param[in] pDataType  Specifies the data type of the attribute to sort by. @n
Specify <tt>STRING</tt> for a string or <tt>INTEGER</tt> for a number. @n
Note that the data type is ignored when sorting on a system attribute.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval ResultOutOfMemory  Insufficient memory.
*/
    nn::Result OrderBy(const char* pName, const char* pOrder = "DESC", const char* pDataType = "STRING");

    /*!
@brief  Sets the sales status filter.

Specify <tt>@ref SALES_STATUS_FILTER_ONSALE</tt> to only search for items that are currently on sale. @n
The filter defaults to <tt>@ref SALES_STATUS_FILTER_ONSALE</tt>.

Specify <tt>@ref SALES_STATUS_FILTER_ALL</tt> to include items that are no longer on sale or are yet to go on sale.

@param[in] filter  Specifies the sales status filter.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval ResultOutOfMemory  Insufficient memory.
*/
    nn::Result SetSalesStatusFilter(SalesStatusFilter filter);

public:
    // internal:
    bool ConvertRequest(char* pBuffer, size_t size, u32 flags) const;

private:
    // 
    NN_EC_IMPL;
};

//! @}

}} // namespace nn::ec

#endif // NN_EC_QUERY_H_