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

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_ACT_API_TIME_ZONE_H_
#define NN_ACT_API_TIME_ZONE_H_


#include "act_TypesTimeZone.h"


#ifdef __cplusplus

namespace nn
{
namespace act
{

//! @addtogroup    nn_act_api
//! @{

//! @name Getting Current Account Information
//! @{

/*!
@brief Gets the name of the time zone set for the current account.

Gets the time zone name in the <tt>tz database</tt> format for the Nintendo Network Account linked to the current account.
Note that this function does not trigger any communication because it retrieves the value from the local cache. @n

Pass a pointer to a buffer with at least as many elements as <tt>ACT_TIME_ZONE_ID_SIZE</tt> for <span class="argument">pTimeZoneId</span>. @n
@n
When it is not a network account, the function succeeds and a blank string is copied to <span class="argument">pTimeZoneId</span>. @n
@n
If the function fails, the value set in the buffer is undefined.
@param[out]     pTimeZoneId     Specifies an out pointer to the buffer that stores the time zone name.
@return Returns the execution result of the function. If the result is used for branching, follow the method described in <tt>@ref nn_act_communication_errorhandling</tt> <i>Error Handling</i>.
@retval       ResultSuccess                       Succeeded. @n
@retval ResultNotInitialized  Indicates that the account library has not been initialized. @n
@retval ResultInvalidPointer  Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument. @n


*/
Result GetTimeZoneId( char* pTimeZoneId );

/*!
@brief Gets the time difference for the time zone set for the current account.

Gets the time difference from UTC in microseconds for the time zone set in the Nintendo Network Account linked to the current account.
Note that this function does not trigger any communication because it retrieves the value from the local cache. @n

Daylight Saving Time is taken into consideration in the time difference, but note that depending on when the local cache is updated, the change might not be reflected immediately after the start and end of Daylight Saving Time.
Also note that when applied to past and future dates and times, there is a high possibility that the time difference value will not match the value on the actual date.
If you require exact time difference data, we recommend using an independent server or other service to resolve the time difference based on the time zone name that can be retrieved with the <tt>@ref nn::act::GetTimeZoneId</tt> function.

@return         Returns a value in microseconds for the difference from UTC for the time zone set in the current account.
If this function is called on a non-network account or while the account library is uninitialized, <tt>0</tt> is returned.
*/
s64 GetUtcOffset( void );

//! @}
//! @name Getting Other Account Information
//! @{

/*!
@brief Gets the name of the time zone set for the account in the specified slot.

Gets the time zone name in the <tt>tz database</tt> format for the Nintendo Network Account linked to the console account in the specified slot.
Note that this function does not trigger any communication because it retrieves the value from the local cache. @n

Pass a pointer to a buffer with at least as many elements as <tt>ACT_TIME_ZONE_ID_SIZE</tt> for <span class="argument">pTimeZoneId</span>. @n
@n
When it is not a network account, the function succeeds and a blank string is copied to <span class="argument">pTimeZoneId</span>. @n
@n
If the function fails, the value set in the buffer is undefined.

@param[out]     pTimeZoneId     Specifies an out pointer to the buffer that stores the time zone name.
@param[in] slotNo  Specifies the slot number.

@return Returns the execution result of the function. If the result is used for branching, follow the method described in <tt>@ref nn_act_communication_errorhandling</tt> <i>Error Handling</i>.
@retval       ResultSuccess                       Succeeded. @n
@retval ResultNotInitialized  Indicates that the account library has not been initialized. @n
@retval         ResultInvalidPointer        Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument. @n
@retval ResultAccountNotFound  Indicates that the account was not found in the specified slot. @n
*/
Result GetTimeZoneIdEx( char* pTimeZoneId, u8 slotNo );

/*!
@brief Gets the time difference for the time zone set for the account in the specified slot.

Gets the time difference from UTC in microseconds for the time zone set in the Nintendo Network Account linked to the console account in the specified slot.
Note that this function does not trigger any communication because it retrieves the value from the local cache. @n

Daylight Saving Time is taken into consideration in the time difference, but note that depending on when the local cache is updated, the change might not be reflected immediately after the start and end of Daylight Saving Time.
Also note that when applied to past and future dates and times, there is a high possibility that the time difference value will not match the value on the actual date.
If you require exact time difference data, we recommend using an independent server or other service to resolve the time difference based on the time zone name that can be retrieved with the <tt>@ref nn::act::GetTimeZoneIdEx</tt> function.

When it is not a network account, the function succeeds and <tt>0</tt> is copied to <span class="argument">pUtcOffset</span>. @n

If the function fails, the value set in the buffer is undefined.

@param[out]     pUtcOffset      Sets an out pointer to the buffer that stores the time difference.
@param[in] slotNo  Specifies the slot number.

@return Returns the execution result of the function. If the result is used for branching, follow the method described in <tt>@ref nn_act_communication_errorhandling</tt> <i>Error Handling</i>.
@retval       ResultSuccess                       Succeeded. @n
@retval ResultNotInitialized  Indicates that the account library has not been initialized. @n
@retval         ResultInvalidPointer        Indicates that an invalid pointer (such as a <tt>NULL</tt> pointer) was passed as an argument. @n
@retval ResultAccountNotFound  Indicates that the account was not found in the specified slot. @n
*/
Result GetUtcOffsetEx( s64* pUtcOffset, u8 slotNo );

//! @}

//! @}

}
}

#endif


#endif  // NN_ACT_API_PRIVATE_H_