/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     util_CLibImpl.h

  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.

  $Rev: 27772 $
 *---------------------------------------------------------------------------*/

/*! @file
    @brief  Utility header for implementing the C interface.

*/

#ifndef NN_UTIL_DETAIL_UTIL_CLIBIMPL_H_
#define NN_UTIL_DETAIL_UTIL_CLIBIMPL_H_

#include <nn/types.h>
#include <nn/util/util_StaticAssert.h>

#ifdef __cplusplus
#include <nn/util/util_TypeTraits.h>
#endif

#ifdef __cplusplus
    /*! @def  NN_EXTERN_C
        @brief  Declares external linkage using C.
*/
    #define NN_EXTERN_C extern "C"
    #define NN_UTIL_DETAIL_CLIBIMPL_DEFINE_BUFFER_CLASS(cname, cppname, size, alignment_holder_type) \
        typedef union cname \
        { \
            char buf[size]; \
            alignment_holder_type alignment_holder; \
            NN_STATIC_ASSERT((size) == sizeof(cppname) && ::nn::util::alignment_of<alignment_holder_type>::value == ::nn::util::alignment_of<cppname>::value); \
        } cname

#else
    #define NN_EXTERN_C extern
    #define NN_UTIL_DETAIL_CLIBIMPL_DEFINE_BUFFER_CLASS(cname, cppname, size, alignment_holder_type) \
        typedef union cname \
        { \
            char buf[size]; \
            alignment_holder_type alignment_holder; \
        } cname
#endif

#define NN_UTIL_DETAIL_CLIBIMPL_DEFINE_ABSTRACT_BUFFER_CLASS(name) typedef struct { bit8 dummy; } name;

#define NN_UTIL_DETAIL_CLIBIMPL_DECLARE_CONVERSION(name, fromC, toC) \
    NN_EXTERN_C toC* name(fromC*); \
    NN_EXTERN_C const toC* name##Const(const fromC*)

#define NN_UTIL_DETAIL_CLIBIMPL_DEFINE_CONVERSION(name, fromC, toC, fromCpp, toCpp) \
    NN_EXTERN_C toC* name(fromC* p) { return reinterpret_cast<toC*>(static_cast<toCpp*>(reinterpret_cast<fromCpp*>(p))); } \
    NN_EXTERN_C const toC* name##Const(const fromC* p) { return reinterpret_cast<const toC*>(static_cast<const toCpp*>(reinterpret_cast<const fromCpp*>(p))); }

#endif

/* @defgroup page_for_c_users  About C Language Wrappers
    @brief  C language wrappers.
    
    @{

The CTR-SDK APIs are mostly written in C++.
C++ APIs cannot be called directly from C language files.

The CTR-SDK provides wrappers that enable you to call the C++ APIs from C source files.

    Mutex Example

In C++, you would use the <tt>@ref nn::os::Mutex</tt> class to use mutexes. The mutex class maintains mutex objects internally.

The names of the wrappers that enable this class to be used in C begin with <tt>nnosMutex</tt>, as shown in the following examples.
These functions have a 1:1 correspondence with the C++ methods.

@li  <tt>@ref nnosMutexInitialize</tt> → <tt>@ref nn::os::Mutex::Initialize</tt> <br>
@li  <tt>@ref nnosMutexLock</tt>       → <tt>@ref nn::os::Mutex::Lock</tt> <br>
@li  <tt>@ref nnosMutexTryLock</tt>    → <tt>@ref nn::os::Mutex::TryLock</tt> <br>
@li  <tt>@ref nnosMutexUnlock</tt>     → <tt>@ref nn::os::Mutex::Unlock</tt> <br>
@li  <tt>@ref nnosMutexInitialize</tt> → <tt>@ref nn::os::Mutex::Initialize</tt> <br>

For more information about a C wrapper function, see the documentation for the corresponding class method.

The <tt>@ref nnosMutex</tt> structure, the data type that stores mutex objects in C, is an exception.
This structure is actually a class instance under the hood, so it cannot be referenced directly from the C language.


    List
    
For a list of modules that can be used in C and C++ code, see the "Modules" page.

<!-- For a list of C functions, see <A HREF="globals.html">File Members</A>.-->

    @}
*/