pdi.h

/*******************************************************************************
* Copyright (C) 2015-2026 Commissariat a l'energie atomique et aux energies alternatives (CEA)
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* * Redistributions of source code must retain the above copyright
*   notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
*   notice, this list of conditions and the following disclaimer in the
*   documentation and/or other materials provided with the distribution.
* * Neither the name of CEA nor the names of its contributors may be used to
*   endorse or promote products derived from this software without specific
*   prior written permission.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
******************************************************************************/

 
#ifndef PDI_H_
#define PDI_H_
 
#include <paraconf.h>
 
#include <pdi/export.h>
#include <pdi/version.h>
 
#ifdef __cplusplus
extern "C" {
#define PDI_UNAVAILABLE_DEPRECATED [[deprecated("PDI_UNAVAILABLE is never used")]]
#define PDI_ERR_CONFIG_DEPRECATED [[deprecated("Use PDI_ERR_SPECTREE instead")]]
#define PDI_ERR_RIGHT_DEPRECATED [[deprecated("Use PDI_ERR_PERMISSION instead")]]
#else
#define PDI_UNAVAILABLE_DEPRECATED
#define PDI_ERR_CONFIG_DEPRECATED
#define PDI_ERR_RIGHT_DEPRECATED
#endif


typedef enum PDI_status_e {
    PDI_OK = 0,
    // initialize the value to workaround a bug in AppleClang 15
    PDI_UNAVAILABLE PDI_UNAVAILABLE_DEPRECATED = (PDI_OK + 1),
    PDI_ERR_SPECTREE,
    PDI_ERR_CONFIG PDI_ERR_CONFIG_DEPRECATED = PDI_ERR_SPECTREE,
    PDI_ERR_VALUE,
    PDI_ERR_PLUGIN,
    PDI_ERR_IMPL,
    PDI_ERR_SYSTEM,
    PDI_ERR_STATE,
    PDI_ERR_PERMISSION,
    PDI_ERR_RIGHT PDI_ERR_RIGHT_DEPRECATED = PDI_ERR_PERMISSION,
    PDI_ERR_TYPE,
    PDI_ERR_INVALIDACTION,
    PDI_ERR_MULTIPLE,
    // it should also always remain last
    PDI_NB_STATUSES_DEFINED
} PDI_status_t;
 
static
#ifdef __cplusplus
    constexpr
#endif
    char const * const PDI_STATUS_MSG[]
    = {"Not an error",
       "Data unavailable",
       "Invalid entry in specification tree",
       "Invalid value expression",
       "Invalid plugin",
       "Missing feature",
       "System error",
       "Precondition not respected",
       "Permission issue",
       "Incorrect type",
       "Invalid action requested",
       "Multiple errors"};

typedef void (*PDI_errfunc_f)(PDI_status_t status, const char* message, void* context);

typedef struct PDI_errhandler_s {
    PDI_errfunc_f func;

    void* context;
 
} PDI_errhandler_t;

extern const PDI_errhandler_t PDI_EXPORT PDI_ASSERT_HANDLER;

extern const PDI_errhandler_t PDI_EXPORT PDI_WARN_HANDLER;

extern const PDI_errhandler_t PDI_EXPORT PDI_NULL_HANDLER;
 

const char PDI_EXPORT * PDI_errmsg(void);

PDI_errhandler_t PDI_EXPORT PDI_errhandler(PDI_errhandler_t handler);



PDI_status_t PDI_EXPORT PDI_init(PC_tree_t conf);

PDI_status_t PDI_EXPORT PDI_finalize(void);

PDI_status_t PDI_EXPORT PDI_version(unsigned long* provided, unsigned long expected);



typedef enum PDI_inout_e {
    PDI_NONE = 0,
    PDI_IN = 1,
    PDI_OUT = 2,
    PDI_INOUT = 3
 
} PDI_inout_t;

PDI_status_t PDI_EXPORT PDI_share(const char* name, const void* data, PDI_inout_t access);

PDI_status_t PDI_EXPORT PDI_access(const char* name, void** buffer, PDI_inout_t inout);

PDI_status_t PDI_EXPORT PDI_release(const char* name);

PDI_status_t PDI_EXPORT PDI_reclaim(const char* name);

PDI_status_t PDI_EXPORT PDI_event(const char* event);

PDI_status_t PDI_EXPORT PDI_expose(const char* name, const void* data, PDI_inout_t access);

PDI_status_t PDI_EXPORT PDI_multi_expose(const char* event_name, const char* name, const void* data, PDI_inout_t access, ...);
 
#ifdef PDI_WITH_DEPRECATED

PDI_status_t PDI_DEPRECATED_EXPORT PDI_transaction_begin(const char* name);

PDI_status_t PDI_DEPRECATED_EXPORT PDI_transaction_end(void);
 
#endif // PDI_WITH_DEPRECATED

 
#ifdef __cplusplus
} // extern C
#endif
 
 
#endif // PDI_H_