include/diagnostics.h

   1 /*
   2  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_SYSTEM_DIAGNOSTICS_H__
  18 #define __TIZEN_SYSTEM_DIAGNOSTICS_H__
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 # endif
  23
  24 #include <stdio.h>
  25 #include <tizen.h>
  26
  27 /**
  28  * @brief Diagnostics context.
  29  * @since_tizen 6.0
  30  */
  31 typedef void* diagnostics_ctx_h;
  32
  33 /**
  34  * @brief Diagnostics data.
  35  * @since_tizen 6.0
  36  */
  37 typedef void* diagnostics_data_h;
  38
  39 /**
  40  * @brief Enumeration for error codes of Diagnostics.
  41  * @since_tizen 6.0
  42  */
  43 typedef enum {
  44     DIAGNOSTICS_ERROR_NONE = TIZEN_ERROR_NONE,                           /**< Successful */
  45     DIAGNOSTICS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  46     DIAGNOSTICS_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR,                   /**< I/O error */
  47     DIAGNOSTICS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,         /**< Out of memory */
  48     DIAGNOSTICS_ERROR_RESOURCE_BUSY = TIZEN_ERROR_RESOURCE_BUSY,         /**< Device or resource busy */
  49     DIAGNOSTICS_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT,                 /**< Time out */
  50     DIAGNOSTICS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,         /**< Not supported */
  51     DIAGNOSTICS_ERROR_TRY_AGAIN = TIZEN_ERROR_TRY_AGAIN,                 /**< Try again */
  52     DIAGNOSTICS_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED  /**< Permission denied */
  53 } diagnostics_error_e;
  54
  55 /**
  56  * @brief Notification callback fired when new bug report arrives.
  57  * @since_tizen 6.0
  58  * @remarks @a ctx should be released with diagnostics_destroy()
  59  *
  60  * @param[in] ctx Diagnostics context handle
  61  * @param[in] user_data The user data passed from the callback registration function
  62  */
  63 typedef void(*diagnostics_notification_cb)(diagnostics_ctx_h ctx, void *user_data);
  64
  65 /**
  66  * @brief Sets the callback for bug report notification.
  67  * @since_tizen 6.0
  68  *
  69  * @param[in] callback A callback function to set
  70  * @param[in] user_data The user data to be passed to the callback function
  71  *
  72  * @return 0 on success, otherwise a negative error value
  73  * @retval #DIAGNOSTICS_ERROR_NONE Success
  74  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
  75  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
  76  * @retval #DIAGNOSTICS_ERROR_RESOURCE_BUSY Callback already registered
  77  * @retval #DIAGNOSTICS_ERROR_IO_ERROR Internal error occured
  78  */
  79 int diagnostics_set_notification_cb(diagnostics_notification_cb callback, void *user_data);
  80
  81 /**
  82  * @brief Unsets the callback for bug report notification.
  83  * @since_tizen 6.0
  84  *
  85  * @return 0 on success, otherwise a negative error value
  86  * @retval #DIAGNOSTICS_ERROR_NONE Success
  87  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
  88  * @retval #DIAGNOSTICS_ERROR_IO_ERROR Internal error occured
  89  */
  90 int diagnostics_unset_notification_cb(void);
  91
  92 /**
  93  * @platform
  94  * @brief Requests client to dump data.
  95  * @since_tizen 6.0
  96  * @privlevel platform
  97  * @privilege
  98  * @remarks @a data should be released with diagnostics_data_destroy().
  99  * This function is permitted only to an app signed by platform level certificates.
 100  *
 101  * @param[in] client_id An id of app or service to request
 102  * @param[in] params Array of parameters
 103  * @param[in] params_size Number of parameters
 104  * @param[out] data Dumpsys data handle
 105  *
 106  * @return 0 on success, otherwise a negative error value
 107  * @retval #DIAGNOSTICS_ERROR_NONE Success
 108  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 109  * @retval #DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied
 110  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 111  * @retval #DIAGNOSTICS_ERROR_IO_ERROR Internal error occured
 112  * @retval #DIAGNOSTICS_ERROR_OUT_OF_MEMORY Not enough memory to create data handle
 113  */
 114 int diagnostics_request_client_data(const char *client_id, const char **params, int params_size, diagnostics_data_h *data);
 115
 116 /**
 117  * @brief Reads diagnostics data.
 118  * @since_tizen 6.0
 119  * @remarks @a data should be released with diagnostics_data_destroy().
 120  *          This function is intended for use in loop until EOF is reached.
 121  *          EOF is when @a bytes_read == 0 and function returns #DIAGNOSTICS_ERROR_NONE.
 122  * @param[in] data Diagnostics data handle
 123  * @param[in,out] buf Buffer to store read data \n
 124  *                    Provided buffer must be large enough to contain @a count number of bytes
 125  * @param[in] count Number of bytes to read
 126  * @param[in] timeout_ms Timeout [ms] for reading requested number of bytes (timeout_ms <= 0 means to wait forever)
 127  * @param[out] bytes_read Real number of read bytes
 128  *
 129  * @return 0 on success, otherwise a negative error value
 130  * @retval #DIAGNOSTICS_ERROR_NONE Success
 131  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 132  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 133  * @retval #DIAGNOSTICS_ERROR_TIMED_OUT Timeout occured
 134  * @retval #DIAGNOSTICS_ERROR_TRY_AGAIN Try again
 135  * @retval #DIAGNOSTICS_ERROR_IO_ERROR Internal error occured while trying to read data, result is unspecified and *bytes_read is not updated
 136  */
 137 int diagnostics_data_read(diagnostics_data_h data, void *buf, size_t count, int timeout_ms, size_t *bytes_read);
 138
 139 /**
 140  * @brief Frees diagnostics data.
 141  * @since_tizen 6.0
 142  *
 143  * @param[in] data Diagnostics data handle
 144  *
 145  * @return 0 on success, otherwise a negative error value
 146  * @retval #DIAGNOSTICS_ERROR_NONE Success
 147  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 148  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 149  */
 150 int diagnostics_data_destroy(diagnostics_data_h data);
 151
 152 /**
 153  * @brief Gets diagnostics context provider's id.
 154  * @since_tizen 6.0
 155  * @remarks @a client_id should be released with free().
 156  *
 157  * @param[in] ctx Diagnostics context handle
 158  * @param[out] client_id An id of the context provider
 159  *
 160  * @return 0 on success, otherwise a negative error value
 161  * @retval #DIAGNOSTICS_ERROR_NONE Success
 162  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 163  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 164  */
 165 int diagnostics_get_client_id(diagnostics_ctx_h ctx, char **client_id);
 166
 167 /**
 168  * @platform
 169  * @brief Gets report data.
 170  * @since_tizen 6.0
 171  * @privlevel platform
 172  * @privilege
 173  * @remarks @a data should be released with diagnostics_data_destroy().
 174  * This function is permitted only to an app signed by platform level certificates.
 175  *
 176  * @param[in] ctx Diagnostics context handle
 177  * @param[in] params Array of parameters \n
 178  *                   Refer to context provider's documentation for available parameters
 179  * @param[in] params_size Number of parameters
 180  * @param[out] data Diagnostics data handle
 181  *
 182  * @return 0 on success, otherwise a negative error value
 183  * @retval #DIAGNOSTICS_ERROR_NONE Success
 184  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 185  * @retval #DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied
 186  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 187  * @retval #DIAGNOSTICS_ERROR_IO_ERROR Internal error occured
 188  * @retval #DIAGNOSTICS_ERROR_OUT_OF_MEMORY Not enough memory to create data handle
 189  */
 190 int diagnostics_get_data(diagnostics_ctx_h ctx, const char **params, int params_size, diagnostics_data_h *data);
 191
 192 /**
 193  * @brief Frees diagnostics context.
 194  * @since_tizen 6.0
 195  *
 196  * @param[in] ctx Diagnostics context handle
 197  *
 198  * @return 0 on success, otherwise a negative error value
 199  * @retval #DIAGNOSTICS_ERROR_NONE Success
 200  * @retval #DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported
 201  * @retval #DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
 202  */
 203 int diagnostics_destroy(diagnostics_ctx_h ctx);
 204
 205 #ifdef __cplusplus
 206 }
 207 #endif
 208
 209 #endif /* __TIZEN_SYSTEM_DIAGNOSTICS_H__ */