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

Copyright (C) 2012 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_BOSS_BOSS_NETTASKSETTING_H_
#define NN_BOSS_BOSS_NETTASKSETTING_H_

#include <nn/boss/boss_Const.h>
#include <nn/boss/boss_Result.h>
#include <nn/boss/boss_Types.h>
#include <nn/boss/boss_TaskSetting.h>

#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup nn_boss_api
  @{
*/

/*!
@brief Represents settings for network-related tasks.
  
The class that makes the task settings for the task that handles the network processing normally inherits this class.
This inheritance enables the use of the methods of this class in common to set the network-related task attributes for any task settings class.
*/
class NetTaskSetting : public TaskSetting
{
public:
/*!
    @brief  Constructor.
*/
    explicit NetTaskSetting(void);

/*!
    @brief  Destructor.
*/
    virtual ~NetTaskSetting(void);


/*!
@brief Sets the HTTP communication information. Applications do not need to use this member function directly. Used by subclasses representing concrete task settings (such as <tt>@ref NbdlTaskSetting</tt>).

@param[in] protocol  Specifies the communication protocol.
@param[in] url  Specifies the connection URL. <tt>@ref URL_MAX_LENGTH_WITH_NULL</tt> defines the maximum length, including the terminating <tt>NULL</tt> character.
@param[in] option  Specifies communication options. Current
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetConnectionSetting(HttpProtocol protocol, const char* url, u16 option = 0);


/*!
@brief Sets the value of <tt>If-Modified-Since</tt> to the <tt>LastModifiedTime</tt> value when a task is executing for the first time.

When tasks are run for the second (or subsequent) time, the <tt>LastModifiedTime</tt> value obtained in the HTTP response header the previous time the task was run is automatically set to <tt>If-Modified-Since</tt>.
If settings are not made with this method, the first time the task is run it is not given an <tt>If-Modified-Since</tt> request header.
Use this method only if you want to give the task an <tt>If-Modified-Since</tt> request header when it is first run.

@param[in] pFirstLastModifiedTime  The <tt>LastModifiedTime</tt> value to set. This string is used as the <tt>If-Modified-Since</tt> request header value without modification. <tt>@ref HTTP_LAST_MODIFIED_TIME_STR_MAX_LENGTH_WITH_NULL</tt> defines the maximum length, including the terminating <tt>NULL</tt> character. 
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetFirstLastModifiedTime(const char* pFirstLastModifiedTime);

/*!
@brief Adds a custom header sent by the task in HTTP communication.

Multiple custom headers can be added.
The string set is sent as is in the [<i>label string</i>]:[<i>value string</i>] format.
<tt>@ref HTTP_REQUEST_PRIVATE_HEADER_MAX_COUNT</tt> defines the maximum number of custom headers that can be added.

@param[in] label  The label string for the custom header being added. <tt>@ref HTTP_REQUEST_HEADER_LABEL_MAX_LENGTH_WITH_NULL</tt> defines the maximum length, including the terminating <tt>NULL</tt> character.
@param[in] value  The value string for the custom header being added. <tt>@ref HTTP_REQUEST_HEADER_VALUE_MAX_LENGTH_WITH_NULL</tt> defines the maximum length, including the terminating <tt>NULL</tt> character.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
@retval ResultFull  The maximum number of custom headers have already been registered.
*/
    nn::Result AddHttpHeader(const char* label, const char* value);


/*!
@brief Clears all registered custom headers.
*/
    void ClearHttpHeaders( void );

/*!
@brief Adds a custom query sent by the task in HTTP communication.

You can add multiple queries.
You can set <tt>@ref QueryKind</tt> to any value that can be obtained from the console, and send this as the query.
<tt>@ref HTTP_PRIVATE_QUERY_MAX_COUNT</tt> defines the maximum number of custom queries that can be added.

@param[in] name  Specifies the name component of the custom query. <tt>@ref HTTP_PRIVATE_QUERY_NAME_MAX_LENGTH_WITH_NULL</tt> defines the maximum length, including the terminating <tt>NULL</tt> character.
@param[in] kind  Specifies the custom query value type.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
@retval ResultFull  The maximum number of custom queries have already been registered.
*/
    nn::Result AddHttpQueryString(const char* name, QueryKind kind);

/*!
@brief Clears all registered custom query strings.
*/
    void ClearHttpQueryStrings( void );


/*!
@brief Adds a built-in CA certificate.

You can add multiple built-in CA certificates.
<tt>@ref HTTP_INTERNAL_CACERT_MAX_COUNT</tt> defines the maximum number of built-in CA certificates that can be added.

@param[in] caCertId  The ID of the CA certificate to add. If you must use an internal CA certificate, contact Nintendo for an ID.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultFull  The maximum number of custom certificates have already been installed.
*/
    nn::Result AddInternalCaCert(s8 caCertId);

/*!
@brief [Unsupported API Function.]

Adds a custom CA certificate.

@param[in] name  The name of the custom certificate to install.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
@retval ResultFull  The maximum number of custom certificates have already been installed.
*/
    nn::Result AddCaCert(const char* name);

/*!
@brief Clears all registered custom certificate information.
*/
    void ClearCaCertSetting( void );


/*!
@brief Sets a built-in client certificate.

You can set only one built-in client certificate. If the argument is omitted, the Wii U console's internal client certificate is configured.

@param[in] clientCertId  Specifies the ID of the built-in client certificate. If you must use a built-in client authentication certificate, contact Nintendo for an ID.
*/
    void SetInternalClientCert(s8 clientCertId = 1);

/*!
@brief [Unsupported API Function.]

Adds a custom client certificate.

@param[in] certName  Specifies the name of the custom certificate to add.
@param[in] keyName  Specifies the name of the key to add.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetClientCert(const char* certName, const char* keyName);

/*!
@brief Clears all registered custom certificate information.
*/
    void ClearClientCertSetting( void );

/*!
@brief Sets the service token. Use this function when you want to authenticate a client on the server using a service token obtained from the account server.

The specified service token is included in HTTP request headers when making an HTTP request.

@param[in] serviceToken  Specifies the service token to set. The value of <tt>@ref SERVICE_TOKEN_SIZE</tt> bytes.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetServiceToken(const u8 serviceToken[SERVICE_TOKEN_SIZE]);

/*!
@brief Specifies communications options. Applications do not need to use this member function directly. Used by subclasses representing concrete task settings (such as <tt>@ref NbdlTaskSetting</tt>).

@param[in] option  Specifies the option to set. Please contact Nintendo about the options that you can set.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetHttpOption(u16 option);

/*!
@brief Specifies the timeout time for HTTP communications. The unit is seconds. Use this function when you want to modify the default timeout time.

In HTTP communications performed when executing tasks, if no data is communicated for this length of time, the task results in a timeout error.
Tasks that are not explicitly specified with this method have a timeout time value of <tt>@ref DEFAULT_TASK_HTTP_TIMEOUT_SEC</tt>.

@param[in] timeoutSec  Specifies the timeout value to set. The unit is seconds.
@return Returns the result of execution. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully retrieved.
@retval ResultInvalidParameter  Invalid parameter.
*/
    nn::Result SetHttpTimeout(u32 timeoutSec);

};

// @}

} // end of namespace boss
} // end of namespace nn

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_NETTASKSETTING_H_ */