Update copyright dates

[src/app-framework-binder.git] / include / afb / afb-binding.h

diff --git a/include/afb/afb-binding.h b/include/afb/afb-binding.h
index 6d92cb8..950cd89 100644 (file)
--- a/include/afb/afb-binding.h
+++ b/include/afb/afb-binding.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2016, 2017 "IoT.bzh"
+ * Copyright (C) 2015-2020 "IoT.bzh"
  * Author: José Bollo <jose.bollo@iot.bzh>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,57 +17,105 @@
 
 #pragma once
 
+/**
+ * @mainpage
+ *
+ * @section brief Brief introduction
+ *
+ * This is part of the AGL framework micro-service binder and is provided as the
+ * API for writing bindings.
+ *
+ * The normal usage is to include only one file as below:
+ *
+ * ```C
+ * #define AFB_BINDING_VERSION 3
+ * #include <afb/afb-binding.h>
+ * ```
+ *
+ * @example tuto-1.c
+ * @example tuto-2.c
+ */
+/**
+ * @file afb/afb-binding.h
+ */
+
 #include <stdarg.h>
+#include <stdint.h>
+#include <json-c/json.h>
+
+/**
+ * @def AFB_BINDING_INTERFACE_VERSION
 
-/*****************************************************************************
- * This files is the main file to include for writing bindings dedicated to
+ *  * Version of the binding interface.
  *
- *                      AFB-DAEMON
+ * This is intended to be test for tuning condition code.
+ * It is of the form MAJOR * 1000 + REVISION.
  *
- * Functions of bindings of afb-daemon are accessible by authorized clients
- * through the apis module of afb-daemon.
+ * @see AFB_BINDING_UPPER_VERSION that should match MAJOR
+ */
+#define AFB_BINDING_INTERFACE_VERSION 3000
+
+/**
+ * @def AFB_BINDING_LOWER_VERSION
  *
- * A binding is a shared library. This shared library must have at least one
- * exported symbol for being registered in afb-daemon.
+ * Lowest binding API version supported.
  *
+ * @see AFB_BINDING_VERSION
+ * @see AFB_BINDING_UPPER_VERSION
  */
+#define AFB_BINDING_LOWER_VERSION     1
 
-#define AFB_BINDING_PRAGMA_KEEP_OBSOLETE_V1
-#define AFB_BINDING_PRAGMA_KEEP_OBSOLETE_V2
-#define AFB_BINDING_PRAGMA_DECLARE_V1
-#define AFB_BINDING_PRAGMA_DECLARE_V2
+/**
+ * @def AFB_BINDING_UPPER_VERSION
+ *
+ * Upper binding API version supported.
+ *
+ * @see AFB_BINDING_VERSION
+ * @see AFB_BINDING_LOWER_VERSION
+ */
+#define AFB_BINDING_UPPER_VERSION     3
 
-#define AFB_BINDING_LOWER_VERSION     1
-#define AFB_BINDING_UPPER_VERSION     2
-#define AFB_BINDING_DEFAULT_VERSION   1
+/**
+ * @def AFB_BINDING_VERSION
+ *
+ * This macro must be defined before including <afb/afb-binding.h> to set
+ * the required binding API.
+ */
 
-#ifndef AFB_BINDING_CURRENT_VERSION
-#define AFB_BINDING_CURRENT_VERSION   AFB_BINDING_DEFAULT_VERSION
+#ifndef AFB_BINDING_VERSION
+#error "\
+\n\
+\n\
+  AFB_BINDING_VERSION should be defined before including <afb/afb-binding.h>\n\
+  AFB_BINDING_VERSION defines the version of binding that you use.\n\
+  Currently the version to use is 3 (older versions: 1 is obsolete, 2 is legacy).\n\
+  Consider to add one of the following define before including <afb/afb-binding.h>:\n\
+\n\
+    #define AFB_BINDING_VERSION 3\n\
+\n\
+"
+#else
+#  if AFB_BINDING_VERSION == 1
+#    warning "Using binding version 1, consider to switch to version 3"
+#  endif
+#  if AFB_BINDING_VERSION == 2
+#    warning "Using binding version 2, consider to switch to version 3"
+#  endif
 #endif
 
-/*
- * Some function of the library are exported to afb-daemon.
- */
+#if AFB_BINDING_VERSION != 0
+# if AFB_BINDING_VERSION < AFB_BINDING_LOWER_VERSION || AFB_BINDING_VERSION > AFB_BINDING_UPPER_VERSION
+#  error "Unsupported binding version AFB_BINDING_VERSION"
+# endif
+#endif
 
-#include "afb-session.h"
-#include "afb-auth.h"
-#include "afb-event-itf.h"
-#include "afb-req-itf.h"
-#include "afb-service-itf.h"
-#include "afb-daemon-itf.h"
+/***************************************************************************************************/
+#include "afb-binding-predefs.h"
 #include "afb-binding-v1.h"
 #include "afb-binding-v2.h"
-
-#if AFB_BINDING_CURRENT_VERSION == 1
-#define afb_binding  afb_binding_v1
-#define afb_binding_interface afb_binding_interface_v1
-#if !defined(AFB_BINDING_PRAGMA_NO_VERBOSE_MACRO)
-#define ERROR   AFB_ERROR_V1
-#define WARNING AFB_WARNING_V1
-#define NOTICE  AFB_NOTICE_V1
-#define INFO    AFB_INFO_V1
-#define DEBUG   AFB_DEBUG_V1
-#endif
+#include "afb-binding-v3.h"
+#if defined(AFB_BINDING_WANT_DYNAPI)
+#  include "afb-dynapi-legacy.h"
 #endif
-
+#include "afb-binding-postdefs.h"