Add API description of cynara_strerror()

Introduce new API call of cynara_strerror() used to obtain error
message from error number.

Change-Id: Ibd5b5a2af700a04fe8b3bfea8fde715b17db3a61

diff --git a/src/common/CMakeLists.txt b/src/common/CMakeLists.txt
index 885e325..07167bc 100644 (file)
--- a/src/common/CMakeLists.txt
+++ b/src/common/CMakeLists.txt
@@ -28,6 +28,7 @@ INCLUDE_DIRECTORIES(
 SET(COMMON_SOURCES
     ${COMMON_PATH}/config/PathConfig.cpp
     ${COMMON_PATH}/containers/BinaryQueue.cpp
+    ${COMMON_PATH}/error/api.cpp
     ${COMMON_PATH}/lock/FileLock.cpp
     ${COMMON_PATH}/log/log.cpp
     ${COMMON_PATH}/plugin/PluginManager.cpp

diff --git a/src/common/error/api.cpp b/src/common/error/api.cpp
new file mode 100644 (file)
index 0000000..d8243b4
--- /dev/null
+++ b/src/common/error/api.cpp
@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+/**
+ * @file        src/common/error/api.cpp
+ * @author      Aleksander Zdyb <a.zdyb@samsung.com>
+ * @version     1.0
+ * @brief       Implementation of cynara_strerror
+ */
+
+#include <cstring>
+
+#include <cynara-error.h>
+
+int cynara_strerror(int errnum, char *buf, size_t buflen) {
+    if (buf == nullptr)
+        return CYNARA_API_INVALID_PARAM;
+
+    const char *message = nullptr;
+
+    switch (errnum) {
+        case CYNARA_API_ACCESS_NOT_RESOLVED:
+            message = "Access not resolved";
+            break;
+        case CYNARA_API_ACCESS_ALLOWED:
+            message = "Access granted";
+            break;
+        case CYNARA_API_ACCESS_DENIED:
+            message = "Access denied";
+            break;
+        case CYNARA_API_SUCCESS:
+            message = "Operation successful";
+            break;
+        case CYNARA_API_CACHE_MISS:
+            message = "Value not in cache";
+            break;
+        case CYNARA_API_MAX_PENDING_REQUESTS:
+            message = "Pending requests exceeded maximum";
+            break;
+        case CYNARA_API_OUT_OF_MEMORY:
+            message = "Out of memory";
+            break;
+        case CYNARA_API_INVALID_PARAM:
+            message = "Invalid param";
+            break;
+        case CYNARA_API_SERVICE_NOT_AVAILABLE:
+            message = "Service not available";
+            break;
+        case CYNARA_API_METHOD_NOT_SUPPORTED:
+            message = "Method not supported";
+            break;
+        case CYNARA_API_OPERATION_NOT_ALLOWED:
+            message = "Operation not allowed";
+            break;
+        case CYNARA_API_OPERATION_FAILED:
+            message = "Operation failed";
+            break;
+        case CYNARA_API_BUCKET_NOT_FOUND:
+            message = "Bucket not found";
+            break;
+        case CYNARA_API_UNKNOWN_ERROR:
+            message = "Unknown error";
+            break;
+        case CYNARA_API_CONFIGURATION_ERROR:
+            message = "Configuration error";
+            break;
+        case CYNARA_API_INVALID_COMMANDLINE_PARAM:
+            message = "Invalid parameter in command-line";
+            break;
+        case CYNARA_API_BUFFER_TOO_SHORT:
+            message = "Buffer too short";
+            break;
+    }
+
+    if (message == nullptr)
+        return CYNARA_API_INVALID_PARAM;
+
+    if (buflen < strlen(message) + 1)
+        return CYNARA_API_BUFFER_TOO_SHORT;
+
+    strcpy(buf, message);
+
+    return CYNARA_API_SUCCESS;
+}

diff --git a/src/include/cynara-error.h b/src/include/cynara-error.h
index ac69412..875d877 100644 (file)
--- a/src/include/cynara-error.h
+++ b/src/include/cynara-error.h
@@ -26,6 +26,8 @@
 #ifndef CYNARA_ERROR_H
 #define CYNARA_ERROR_H
 
+#include <stddef.h>
+
 /**
  * \name Return Codes
  * exported by the foundation API.
@@ -79,6 +81,59 @@
 
 /*! \brief   indicating invalid parameter in command-line */
 #define CYNARA_API_INVALID_COMMANDLINE_PARAM    -12
+
+/*! \brief   indicating that provided buffer is too short */
+#define CYNARA_API_BUFFER_TOO_SHORT             -13
 /** @}*/
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \par Description:
+ * Returns the error string in the user-supplied buffer buf of length buflen.
+ *
+ * \par Purpose:
+ * This function populates passed argument buf with a string that describes the error code
+ * passed in the argument errnum, possibly using the LC_MESSAGES part of the current locale
+ * to select the appropriate language.
+ *
+ * \par Typical use case:
+ * Once after any of API functions returns negative value (if the error message is to be presented
+ * to the user).
+ *
+ * \par Method of function operation:
+ * This function copies error string to memory pointed by argument buf along with termination
+ * character ('\0').
+ *
+ * \par Sync (or) async:
+ * This is a synchronous API.
+ *
+ * \par Thread-safety:
+ * This function is thread-safe as long as setlocale() is not invoked concurrently.
+ *
+ * \par Important notes:
+ * This function copies error string to memory pointed by argument buf only if the buffer is
+ * of sufficient size (indicated by argument buflen). User is responsible for allocating sufficient
+ * memory for both error string and termination character ('\0').
+ * Moreover, the user must not invoke setlocale() concurrently with this function, because results
+ * are unspecified.
+ *
+ * \param[in] errnum error number
+ * \param[out] buf buffer for error message
+ * \param[in] buflen buffer size
+ *
+ * \return CYNARA_API_SUCCESS on success, CYNARA_API_BUFFER_TOO_SHORT, if error message couldn't fit
+ *         into allocated buffer, or CYNARA_API_INVALID_PARAM if errnum is not a valid error number
+ *         or argument buf is NULL.
+ *
+ * \brief Obtain error message from error number.
+ */
+int cynara_strerror(int errnum, char *buf, size_t buflen);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* CYNARA_ERROR_H */