nanocoat/include/sjme/native.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Native Shelf Abstraction (NAL).
  12  *
  13  * @since 2023/07/29
  14  */
  15
  16 #ifndef SQUIRRELJME_NATIVE_H
  17 #define SQUIRRELJME_NATIVE_H
  18
  19 #include "sjme/stdTypes.h"
  20 #include "sjme/error.h"
  21 #include "sjme/seekable.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_NATIVE_H
  28 extern "C" {
  29         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  30 #endif     /* #ifdef __cplusplus */
  31
  32 /*--------------------------------------------------------------------------*/
  33
  34 /**
  35  * Returns the current time in milliseconds as per the Java
  36  * method @c System::currentTimeMillis() .
  37  *
  38  * @param result The resultant time.
  39  * @return any resultant error code.
  40  * @since 2023/05/23
  41  */
  42 typedef sjme_errorCode (*sjme_nal_currentTimeMillisFunc)(
  43         sjme_attrOutNotNull sjme_jlong* result)
  44         sjme_attrCheckReturn;
  45
  46 /**
  47  * Opens the given file natively.
  48  *
  49  * @param inPool The pool for allocations.
  50  * @param inPath The path to open.
  51  * @param outSeekable The seekable to open within.
  52  * @return Any resultant error, if any.
  53  * @since 2024/08/11
  54  */
  55 typedef sjme_errorCode (*sjme_nal_fileOpenFunc)(
  56         sjme_attrInNotNull sjme_alloc_pool* inPool,
  57         sjme_attrInNotNull sjme_lpcstr inPath,
  58         sjme_attrOutNotNull sjme_seekable* outSeekable);
  59
  60 /**
  61  * Reads from the system environment a variable.
  62  *
  63  * @param buf The output buffer.
  64  * @param bufLen The length of the buffer to store within.
  65  * @param env The environment variable to lookup.
  66  * @return Any resultant error code. Will return @c SJME_ERROR_NO_SUCH_ELEMENT
  67  * if there is no environment variable with the given name.
  68  * @since 2023/08/05
  69  */
  70 typedef sjme_errorCode (*sjme_nal_getEnvFunc)(
  71         sjme_attrInNotNull sjme_attrOutNotNullBuf(len) sjme_lpstr buf,
  72         sjme_attrInPositiveNonZero sjme_jint bufLen,
  73         sjme_attrInNotNull sjme_lpcstr env)
  74         sjme_attrCheckReturn;
  75
  76 /**
  77  * Returns the current nanosecond monotonic class as per the Java
  78  * method @c System::nanoTime() .
  79  *
  80  * @param result The resultant time.
  81  * @return Any resultant error code.
  82  * @since 2023/05/23
  83  */
  84 typedef sjme_errorCode (*sjme_nal_nanoTimeFunc)(
  85         sjme_attrOutNotNull sjme_jlong* result)
  86         sjme_attrCheckReturn;
  87
  88 /**
  89  * Formatted text to standard stream.
  90  *
  91  * @param format The format string.
  92  * @param ... Format arguments.
  93  * @return Any resultant error code.
  94  * @since 2024/08/08
  95  */
  96 typedef sjme_errorCode (*sjme_nal_stdFFunc)(
  97         sjme_attrInNotNull sjme_lpcstr format,
  98         ...);
  99
 100 /**
 101  * Native Abstraction Layer functions.
 102  *
 103  * @since 2023/07/29
 104  */
 105 typedef struct sjme_nal
 106 {
 107         /** Current time in milliseconds. */
 108         sjme_nal_currentTimeMillisFunc currentTimeMillis;
 109
 110         /** Opens a given native file. */
 111         sjme_nal_fileOpenFunc fileOpen;
 112
 113         /** Get environment variable. */
 114         sjme_nal_getEnvFunc getEnv;
 115
 116         /** Get the current monotonic nanosecond time. */
 117         sjme_nal_nanoTimeFunc nanoTime;
 118
 119         /** Formatted output to standard error. */
 120         sjme_nal_stdFFunc stdErrF;
 121
 122         /** Formatted output to standard output. */
 123         sjme_nal_stdFFunc stdOutF;
 124 } sjme_nal;
 125
 126 /** Default native abstraction layer. */
 127 extern const sjme_nal sjme_nal_default;
 128
 129 #if !defined(SJME_CONFIG_MISSING_ERRNO)
 130
 131 /**
 132  * Maps @c errno to a SquirrelJME error.
 133  *
 134  * @param errNum The error number.
 135  * @return The resultant error.
 136  * @since 2024/08/11
 137  */
 138 sjme_errorCode sjme_nal_errno(sjme_jint errNum);
 139
 140 #else
 141
 142 /**
 143  * Maps @c errno to a SquirrelJME error.
 144  *
 145  * @param errNum The error number.
 146  * @return The resultant error.
 147  * @since 2024/08/11
 148  */
 149 #define sjme_nal_errno(ignored) ((sjme_errorCode)(SJME_ERROR_NATIVE_ERROR))
 150
 151 #endif
 152
 153 /*--------------------------------------------------------------------------*/
 154
 155 /* Anti-C++. */
 156 #ifdef __cplusplus
 157         #ifdef SJME_CXX_SQUIRRELJME_NATIVE_H
 158 }
 159                 #undef SJME_CXX_SQUIRRELJME_NATIVE_H
 160                 #undef SJME_CXX_IS_EXTERNED
 161         #endif /* #ifdef SJME_CXX_SQUIRRELJME_NATIVE_H */
 162 #endif     /* #ifdef __cplusplus */
 163
 164 #endif /* SQUIRRELJME_NATIVE_H */