IOT-1375 Add OC_DEPRECATED macros 11/23111/12
authorGeorge Nash <george.nash@intel.com>
Thu, 9 Nov 2017 17:50:03 +0000 (09:50 -0800)
committerDave Thaler <dthaler@microsoft.com>
Thu, 4 Jan 2018 20:20:15 +0000 (20:20 +0000)
This add macros that enable marking deprecated for the compiler
This will add compiler specific annotations that will
cause compiler warnings when a deprecated function is used.

Adding the date the function was deprecated, was inspired by
the AllJoyn project. Adding the date a function or class was
deprecated can help when deciding to remove deprecated code.

The doxygen config files were modified to expand the macros
so doxygen properly documents the deprecated function not the
OC_DEPRECATED macro itself.

The macro was then used to mark the base64 implementation
deprecated. Since the base64 implementation is currently placed
in the public header files we should mark it as deprecated giving
other users time to move their code to the mbedtls
implementation.

Change-Id: I6e13e34caf84311e555d19aeb393e922d09d4b59
Signed-off-by: George Nash <george.nash@intel.com>
resource/c_common/platform_features.h
resource/csdk/security/include/base64.h
resource/csdk/security/unittest/SConscript
resource/docs/c-doc/Doxyfile
resource/docs/c-doc/devdocs.doxyfile
resource/docs/cpp-doc/Doxyfile
resource/docs/cpp-doc/devdocs.doxyfile

index 9b572bf..686bec2 100644 (file)
 #  define OC_CALL
 #endif
 
+#if defined(__GNUC__)
+#  if (__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1))
+/** mark a function as deprecated, with date of applying this macro (date format: YYYY.MM). */
+#    define OC_DEPRECATED(func, date)  func __attribute__((deprecated))
+/** mark a class as deprecated, with date of applying this macro (date format: YYYY.MM). */
+#    define OC_DEPRECATED_CLASS(date) __attribute__((deprecated))
+
+#    if (__GNUC__ >= 5) || ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 5))
+/** same as OC_DEPRECATED, but with user-defined text message to be displayed. */
+#      define OC_DEPRECATED_MSG(func, msg, date) func __attribute__((deprecated(msg)))
+/** same as OC_DEPRECATED_CLASS, but with user-defined text message to be displayed. */
+#      define OC_DEPRECATED_CLASS_MSG(msg, date) __attribute__((deprecated(msg)))
+#    else
+       /* gcc versions older than 4.5 do not support the text message. */
+/** same as OC_DEPRECATED, but with user-defined text message to be displayed. */
+#      define OC_DEPRECATED_MSG(func, msg, date) OC_DEPRECATED(func, date)
+/** same as OC_DEPRECATED_CLASS, but with user-defined text message to be displayed. */
+#      define OC_DEPRECATED_CLASS_MSG(msg, date) OC_DEPRECATED_CLASS(date)
+#    endif // GCC version >= 4.5
+#  else
+     /* not all gcc versions support the depricated attribute. */
+/** mark a function as deprecated, with date of applying this macro (date format: YYYY.MM). */
+#    define OC_DEPRECATED(func, date) func
+/** mark a class as deprecated, with date of applying this macro (date format: YYYY.MM). */
+#    define OC_DEPRECATED_CLASS(date)
+/** same as OC_DEPRECATED, but with user-defined text message to be displayed. */
+#    define OC_DEPRECATED_MSG(func, msg, date) func
+/** same as OC_DEPRECATED_CLASS, but with user-defined text message to be displayed. */
+#    define OC_DEPRECATED_CLASS_MSG(msg, date)
+#  endif // GCC version >= 3.1
+#elif defined(_MSC_VER)
+/** mark a function as deprecated with date of applying this macro (date format: YYYY.MM). */
+#  define OC_DEPRECATED(func, date) __declspec(deprecated) func
+/** mark a class as deprecated  with date of applying this macro (date format: YYYY.MM). */
+#  define OC_DEPRECATED_CLASS(date) __declspec(deprecated)
+/** same as OC_DEPRECATED, but with user-defined text message to be displayed. */
+#  define OC_DEPRECATED_MSG(func, msg, date) __declspec(deprecated(msg)) func
+/** same as OC_DEPRECATED_CLASS, but with user-defined text message to be displayed. */
+#  define OC_DEPRECATED_CLASS_MSG(msg, date) __declspec(deprecated(msg))
+#else /* Some unknown compiler */
+/** mark a function as deprecated with date of applying this macro (date format: YYYY.MM). */
+#  define OC_DEPRECATED(func, date) func
+/** mark a class as deprecated  with date of applying this macro (date format: YYYY.MM). */
+#  define OC_DEPRECATED_CLASS(date)
+/** same as OC_DEPRECATED, but with user-defined text message to be displayed. */
+#  define OC_DEPRECATED_MSG(func, msg, date) func
+/** same as OC_DEPRECATED_CLASS, but with user-defined text message to be displayed. */
+#  define OC_DEPRECATED_CLASS_MSG(msg, date)
+#endif /* Compiler type */
+
 #endif
index 9685b72..4541176 100644 (file)
@@ -21,6 +21,7 @@
 #ifndef _IOTVT_B64_H_
 #define _IOTVT_B64_H_
 
+#include "iotivity_config.h"
 #include <stdint.h>
 #include <stdio.h>
 
@@ -39,6 +40,9 @@ extern "C" {
  * defined in RFC4648 are not implemented. Base 64 encoding with URL
  * and filename safe alphabet, Bass 32, and Base 16 Encoding are not
  * implemented.
+ *
+ * @deprecated This implementation of base64 has been deprecated in favor of
+ * the base64 implementation that is available as part of the mbedtls library
  */
 
 /**
@@ -91,9 +95,17 @@ typedef enum
  * @note `outBuf` adds a NULL to the string configuration.
  *
  * @return ::B64_OK for Success, otherwise some error value.
+ *
+ * @deprecated This implementation of base64 encode has been deprecated in favor
+ * of the base64 implementation that is available as part of the mbedtls library.
+ * @see mbedtls_base64_encode()
+ *
  */
+OC_DEPRECATED_MSG(
 B64Result b64Encode(const uint8_t *in, const size_t inLen,
-                    char *outBuf, const size_t outBufSize, size_t *outLen);
+                    char *outBuf, const size_t outBufSize, size_t *outLen),
+                    "Please use mbedtls implementation",
+                    2017.11);
 
 /**
  * Decode the encoded message in base64.
@@ -116,9 +128,16 @@ B64Result b64Encode(const uint8_t *in, const size_t inLen,
  * @param[out] outLen is the byte length of decoded message.
  *
  * @return ::B64_OK for Success, otherwise some error value.
+ *
+ * @deprecated This implementation of base64 decode has been deprecated in favor
+ * of the base64 implementation that is available as part of the mbedtls library.
+ * @see mbedtls_base64_decode()
  */
+OC_DEPRECATED_MSG(
 B64Result b64Decode(const char *in, const size_t inLen,
-                    uint8_t *outBuf, size_t outBufSize, size_t *outLen);
+                    uint8_t *outBuf, size_t outBufSize, size_t *outLen),
+                    "Please use mbedtls implementation",
+                    2017.11);
 
 #ifdef __cplusplus
 }
index 111b2c5..f7278e2 100644 (file)
@@ -74,10 +74,13 @@ if srmtest_env.get('MULTIPLE_OWNER') == '1':
 
 if target_os == 'windows':
     srmtest_env.AppendUnique(LIBS=['sqlite3'])
+    #Disable deprecated code warning we are still testing deprecated functions till they are removed.
+    srmtest_env.AppendUnique(CCFLAGS=['/wd4996'])
 else:
     # TODO: Implement feature check.
     srmtest_env.AppendUnique(CPPDEFINES=['HAVE_LOCALTIME_R'])
-
+    #Disable deprecated code warning we are still testing deprecated functions till they are removed.
+    srmtest_env.AppendUnique(CFLAGS=['-Wno-attributes'])
     if target_os in ['linux', 'tizen']:
         srmtest_env.ParseConfig('pkg-config --cflags --libs sqlite3')
         srmtest_env.ParseConfig('pkg-config --cflags --libs gobject-2.0 gio-2.0 glib-2.0')
index 8949d63..266c05e 100644 (file)
@@ -1531,13 +1531,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1565,7 +1565,11 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = "OC_DEPRECATED(func,date)=func" \
+                         "OC_DEPRECATED_CLASS(date)=" \
+                         "OC_DEPRECATED_MSG(func, msg, date)=func" \
+                         "OC_DEPRECATED_CLASS_MSG(msg, date)="
+
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
index 3c6695c..b72bea7 100644 (file)
@@ -294,12 +294,15 @@ PERLMOD_MAKEVAR_PREFIX =
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
-EXPAND_ONLY_PREDEF     = NO
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             =
+PREDEFINED             = "OC_DEPRECATED(func,date)=func" \
+                         "OC_DEPRECATED_CLASS(date)=" \
+                         "OC_DEPRECATED_MSG(func, msg, date)=func" \
+                         "OC_DEPRECATED_CLASS_MSG(msg, date)="
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
index 997bea6..98bc052 100644 (file)
@@ -1533,13 +1533,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1567,7 +1567,10 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = "OC_DEPRECATED(func,date)=func" \
+                         "OC_DEPRECATED_CLASS(date)=" \
+                         "OC_DEPRECATED_MSG(func, msg, date)=func" \
+                         "OC_DEPRECATED_CLASS_MSG(msg, date)="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
index 8d38f28..ee6f6da 100644 (file)
@@ -276,12 +276,15 @@ PERLMOD_MAKEVAR_PREFIX =
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
-EXPAND_ONLY_PREDEF     = NO
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             =
+PREDEFINED             = "OC_DEPRECATED(func,date)=func" \
+                         "OC_DEPRECATED_CLASS(date)=" \
+                         "OC_DEPRECATED_MSG(func, msg, date)=func" \
+                         "OC_DEPRECATED_CLASS_MSG(msg, date)="
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------