Tizen(Headed) Native API
6.5
|
The Diagnostics API provides functions to send and receive diagnostic events and data from other applications/services.
Required Header
#include <diagnostics.h>
Overview
This Diagnostics API allows applications to exchange diagnostic information.
Client - a program using this API. In case of applications, client ID is set to the application ID, but services must set their ID explicitly using diagnostics_set_client_id().
Provider - a client that sends diagnostic events or serves diagnostic data.
Subscriber - a client that subscribes to diagnostic events or requests diagnostic data.
Event - simple signal sent to all subscribed clients.
Event may be sent with additional data (bundle).
There is a diagnostic context associated with the event, which holds information about sender (client ID), event name and event data.
Data - any data, logs or files sent by providers via this API (dumpsys underneath).
Subscribers may specify additional parameters when requesting diagnostic data. Based on this parameters, providers send appropriate data.
Bugreport - diagnostic report created on demand with diagnostics_request_bugreport().
Bugreport may be process-specific (when pid argument is given) or system-specific (when pid <= 0).
Related Features
This API is related with the following feature:
- http://tizen.org/feature/diagnostics
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information,thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | diagnostics_set_notification_cb (diagnostics_notification_cb callback, void *user_data) |
Sets the callback for diagnostics event notification. | |
int | diagnostics_unset_notification_cb (void) |
Unsets the callback for diagnostics event notification. | |
int | diagnostics_subscribe_event (const char *event_name, const char *client_id) |
Subscribes to an event sent by diagnostics client. | |
int | diagnostics_set_data_request_cb (diagnostics_request_cb callback, void *user_data) |
Sets the callback for diagnostics data request. | |
int | diagnostics_unset_data_request_cb (void) |
Unsets the callback for diagnostics data request. | |
int | diagnostics_request_client_data (const char *client_id, const char **params, int params_size, diagnostics_data_h *data) |
Requests diagnostics client to dump data. | |
int | diagnostics_get_data (diagnostics_ctx_h ctx, const char **params, int params_size, diagnostics_data_h *data) |
Requests diagnostics context's provider to dump data. | |
int | diagnostics_data_get_fd (diagnostics_data_h data, int *fd) |
Gets a file descriptor for diagnostics data. | |
int | diagnostics_data_read (diagnostics_data_h data, void *buf, size_t count, int timeout_ms, size_t *bytes_read) |
Reads diagnostics data. | |
int | diagnostics_data_write (diagnostics_data_h data, const void *buf, size_t count, size_t *bytes_written) |
Writes diagnostics data. | |
int | diagnostics_send_event (const char *event_name, bundle *event_data) |
Sends diagnostics event. | |
int | diagnostics_get_client_id (diagnostics_ctx_h ctx, char **client_id) |
Gets diagnostics client ID (event sender). | |
int | diagnostics_get_event_name (diagnostics_ctx_h ctx, char **event_name) |
Gets diagnostics event name. | |
int | diagnostics_get_event_data (diagnostics_ctx_h ctx, bundle **event_data) |
Gets diagnostics event data. | |
int | diagnostics_set_client_id (const char *client_id) |
Sets the diagnostics client ID. | |
int | diagnostics_request_bugreport (int pid) |
Requests bugreport creation. | |
int | diagnostics_data_destroy (diagnostics_data_h data) |
Frees diagnostics data. | |
int | diagnostics_destroy (diagnostics_ctx_h ctx) |
Frees diagnostics context. | |
Typedefs | |
typedef void * | diagnostics_ctx_h |
Diagnostics context. | |
typedef void * | diagnostics_data_h |
Diagnostics data. | |
typedef void(* | diagnostics_notification_cb )(diagnostics_ctx_h ctx, void *user_data) |
Notification callback fired when new diagnostics event arrives. | |
typedef void(* | diagnostics_request_cb )(diagnostics_data_h data, char **params, int params_size, diagnostics_ctx_h ctx, void *user_data) |
Request callback fired when someone requests diagnostics data. |
Typedef Documentation
typedef void* diagnostics_ctx_h |
Diagnostics context.
- Since :
- 6.0
typedef void* diagnostics_data_h |
Diagnostics data.
- Since :
- 6.0
typedef void(* diagnostics_notification_cb)(diagnostics_ctx_h ctx, void *user_data) |
Notification callback fired when new diagnostics event arrives.
- Since :
- 6.0
- Remarks:
- ctx should be released with diagnostics_destroy().
- Parameters:
-
[in] ctx Diagnostics context handle [in] user_data The user data passed from the callback registration function
typedef void(* diagnostics_request_cb)(diagnostics_data_h data, char **params, int params_size, diagnostics_ctx_h ctx, void *user_data) |
Request callback fired when someone requests diagnostics data.
- Since :
- 6.5
- Remarks:
- data should be released with diagnostics_data_destroy().
- Parameters:
-
[in] data Diagnostics data handle [in] params Array of request's parameters
This array is owned by data, so it is available until data is released
params are the same as passed to diagnostics_request_client_data() or diagnostics_get_data()[in] params_size Number of parameters [in] ctx Diagnostics context handling an event that the request is related to
ctx is available when data has been requested with diagnostics_get_data()
ctx is NULL when data has been requested with diagnostics_request_client_data()
This parameter allows diagnostics client to find diagnostics data related to the specific event[in] user_data The user data passed from the callback registration function
Enumeration Type Documentation
enum diagnostics_error_e |
Enumeration for error codes of Diagnostics.
- Since :
- 6.0
- Enumerator:
Function Documentation
int diagnostics_data_destroy | ( | diagnostics_data_h | data | ) |
Frees diagnostics data.
- Since :
- 6.0
- Parameters:
-
[in] data Diagnostics data handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
int diagnostics_data_get_fd | ( | diagnostics_data_h | data, |
int * | fd | ||
) |
Gets a file descriptor for diagnostics data.
- Since :
- 6.5
- Remarks:
- This function provides a file descriptor to read/write diagnostic data in a custom way instead of using our diagnostics_data_read() and diagnostics_data_write() functions.
Moreover, keep in mind that reading is allowed for diagnostic data subscribers and writing is allowed for providers.
- Parameters:
-
[in] data Diagnostics data handle [in,out] fd A file descriptor related to diagnostics data
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
int diagnostics_data_read | ( | diagnostics_data_h | data, |
void * | buf, | ||
size_t | count, | ||
int | timeout_ms, | ||
size_t * | bytes_read | ||
) |
Reads diagnostics data.
- Since :
- 6.0
- Remarks:
- This function is dedicated to diagnostic information subscribers.
It is intended for use in loop until EOF is reached. EOF is when bytes_read == 0 and function returns DIAGNOSTICS_ERROR_NONE.
- Parameters:
-
[in] data Diagnostics data handle [in,out] buf Buffer to store read data
Provided buffer must be large enough to contain a count number of bytes[in] count Number of bytes to read [in] timeout_ms Timeout [ms] for reading requested number of bytes (timeout_ms <= 0 means to wait forever) [out] bytes_read Real number of bytes read
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_TIMED_OUT Timeout occurred DIAGNOSTICS_ERROR_TRY_AGAIN Try again DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred while trying to read data, result is unspecified and *bytes_read is not updated
int diagnostics_data_write | ( | diagnostics_data_h | data, |
const void * | buf, | ||
size_t | count, | ||
size_t * | bytes_written | ||
) |
Writes diagnostics data.
- Since :
- 6.5
- Remarks:
- This function is dedicated to diagnostic information providers.
Data is being written to the special file descriptor and then copied to the diagnostic information subscriber's endpoint.
- Parameters:
-
[in] data Diagnostics data handle [in] buf Buffer with data to write
Provided buffer must be of size not less than a count number of bytes[in] count Number of bytes to write [out] bytes_written Real number of bytes written
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_TRY_AGAIN Try again DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred while trying to write data, result is unspecified and *bytes_written is not updated
int diagnostics_destroy | ( | diagnostics_ctx_h | ctx | ) |
Frees diagnostics context.
- Since :
- 6.0
- Parameters:
-
[in] ctx Diagnostics context handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
int diagnostics_get_client_id | ( | diagnostics_ctx_h | ctx, |
char ** | client_id | ||
) |
Gets diagnostics client ID (event sender).
- Since :
- 6.0
- Remarks:
- This function is dedicated to diagnostic information subscribers.
client_id should be released with free().
- Parameters:
-
[in] ctx Diagnostics context handle [out] client_id ID of the diagnostics client
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
void notification_handler(diagnostics_ctx_h ctx, void *user_data) { char *client_id; diagnostics_get_client_id(ctx, &client_id); // Process diagnostics event free(client_id); diagnostics_destroy(ctx); }
int diagnostics_get_data | ( | diagnostics_ctx_h | ctx, |
const char ** | params, | ||
int | params_size, | ||
diagnostics_data_h * | data | ||
) |
Requests diagnostics context's provider to dump data.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.0
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information subscribers.
It is permitted only to an app signed by platform level certificates.
data should be released with diagnostics_data_destroy().
The difference between this function and diagnostics_request_client_data() is that this function sends back the whole context to the context's provider to help it find the data specific to the generated event.
- Parameters:
-
[in] ctx Diagnostics context handle [in] params Array of parameters
Refer to specific diagnostics client's documentation for available parameters[in] params_size Number of parameters [out] data Diagnostics data handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred DIAGNOSTICS_ERROR_OUT_OF_MEMORY Not enough memory to create data handle
void notification_handler(diagnostics_ctx_h ctx, void *user_data) { diagnostics_data_h data; const char *params[] = {"foo", "bar", "baz"}; // Request more data from the client that the event came from diagnostics_get_data(ctx, params, sizeof(params)/sizeof(char*), &data); // Read data diagnostics_data_destroy(data); diagnostics_destroy(ctx); }
int diagnostics_get_event_data | ( | diagnostics_ctx_h | ctx, |
bundle ** | event_data | ||
) |
Gets diagnostics event data.
- Since :
- 6.5
- Remarks:
- This function is dedicated to diagnostic information subscribers.
event_data should be released with bundle_free().
- Parameters:
-
[in] ctx Diagnostics context handle [out] event_data Data that came with the diagnostics event (may be NULL when no data has been provided)
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Diagnostics feature is missing or the function has been called by application, not system service DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
void notification_handler(diagnostics_ctx_h ctx, void *user_data) { bundle *event_data; diagnostics_get_event_data(ctx, &event_data); // Process diagnostics event bundle_free(event_data); diagnostics_destroy(ctx); }
int diagnostics_get_event_name | ( | diagnostics_ctx_h | ctx, |
char ** | event_name | ||
) |
Gets diagnostics event name.
- Since :
- 6.5
- Remarks:
- This function is dedicated to diagnostic information subscribers.
event_name should be released with free().
- Parameters:
-
[in] ctx Diagnostics context handle [out] event_name Name of the diagnostics event
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid
void notification_handler(diagnostics_ctx_h ctx, void *user_data) { char *event_name; diagnostics_get_event_name(ctx, &event_name); // Process diagnostics event free(event_name); diagnostics_destroy(ctx); }
int diagnostics_request_bugreport | ( | int | pid | ) |
Requests bugreport creation.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.5
- Privilege Level:
- platform
- Privilege:
- http://tizen.org/privilege/bugreport.admin
- Remarks:
- This function is dedicated to diagnostic information subscribers.
To get bugreport's content, user must subscribe to 'BugreportCreated' diagnostics event, which is sent by crash-service after creating the report.
- Parameters:
-
[in] pid ID of a process that should be livedumped. When pid <= 0, system-wide bugreport is created.
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid or the caller ID not set (required for system services only) DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
int diagnostics_request_client_data | ( | const char * | client_id, |
const char ** | params, | ||
int | params_size, | ||
diagnostics_data_h * | data | ||
) |
Requests diagnostics client to dump data.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.0
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information subscribers.
It is permitted only to an app signed by platform level certificates.
data should be released with diagnostics_data_destroy().
- Parameters:
-
[in] client_id An ID of application or service to request [in] params Array of parameters
Refer to specific diagnostics client's documentation for available parameters[in] params_size Number of parameters [out] data Dumpsys data handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred DIAGNOSTICS_ERROR_OUT_OF_MEMORY Not enough memory to create data handle
#include <diagnostics.h> int main(int argc, char **argv) { diagnostics_data_h data; const char *params[] = {"foo", "bar", "baz"}; char buf[1000]; size_t bytes_read; diagnostics_request_client_data("diagnostics-client", params, sizeof(params)/sizeof(char*), &data); while (true) { diagnostics_data_read(data, buf, sizeof(buf)/sizeof(char), -1, &bytes_read); if (bytes_read == 0) // Reached EOF break; // Process the chunk of data } diagnostics_data_destroy(data); }
int diagnostics_send_event | ( | const char * | event_name, |
bundle * | event_data | ||
) |
Sends diagnostics event.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.5
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information providers.
It is permitted only to an app signed by platform level certificates.
- Parameters:
-
[in] event_name Diagnostics event name [in] event_data Event data or NULL.
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid or the caller ID not set (required for system services only) DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
int main(int argc, char *argv[]) { bundle *event_data = bundle_create(); // This is required for services only, not applications diagnostics_set_client_id("diagnostics-client"); bundle_add_str(event_data, "somekey", "somevalue"); diagnostics_send_event("ConnectionBroken", event_data); bundle_free(event_data); }
int diagnostics_set_client_id | ( | const char * | client_id | ) |
Sets the diagnostics client ID.
- Since :
- 6.5
- Remarks:
- This function is dedicated to diagnostic information providers.
As services do not have any name associated with them, ID must be set explicitly with this function before calling any of the following functions:
diagnostics_set_data_request_cb()
diagnostics_send_event()
diagnostics_request_bugreport()
For applications, client ID is set to the application ID and cannot be changed.
- Parameters:
-
[in] client_id Diagnostics client ID to set.
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_RESOURCE_BUSY Client ID has already been set, not possible to change DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
int diagnostics_set_data_request_cb | ( | diagnostics_request_cb | callback, |
void * | user_data | ||
) |
Sets the callback for diagnostics data request.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.5
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information providers.
It is permitted only to an app signed by platform level certificates.
- Parameters:
-
[in] callback A callback function to set [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid or the caller ID not set (required for system services only) DIAGNOSTICS_ERROR_RESOURCE_BUSY Callback already registered DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
#include <diagnostics.h> static void data_request_cb(diagnostics_data_h data, char **params, int params_size, diagnostics_ctx_h ctx, void *user_data) { const char *buf = "Some data"; size_t bytes_written; diagnostics_data_write(data, buf, sizeof(buf)/sizeof(char), &bytes_written); diagnostics_data_destroy(data); } static GMainLoop *mainloop = NULL; int main(int argc, char **argv) { diagnostics_data_h data; // This is required for services only, not applications diagnostics_set_client_id("diagnostics-client"); diagnostics_set_data_request_cb(data_request_cb, NULL); mainloop = g_main_loop_new(NULL, FALSE); g_main_loop_run(mainloop); }
int diagnostics_set_notification_cb | ( | diagnostics_notification_cb | callback, |
void * | user_data | ||
) |
Sets the callback for diagnostics event notification.
- Since :
- 6.0
- Remarks:
- This function is dedicated to diagnostic information subscribers.
- Parameters:
-
[in] callback A callback function to set [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_RESOURCE_BUSY Callback already registered DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
#include <diagnostics.h> static void notification_handler(diagnostics_ctx_h ctx, void *user_data) { // Process diagnostics event diagnostics_destroy(ctx); } static GMainLoop *mainloop = NULL; int main(int argc, char **argv) { diagnostics_set_notification_cb(notification_handler, NULL); diagnostics_subscribe_event("ConnectionBroken", "org.tizen.someapp"); mainloop = g_main_loop_new(NULL, FALSE); g_main_loop_run(mainloop); }
int diagnostics_subscribe_event | ( | const char * | event_name, |
const char * | client_id | ||
) |
Subscribes to an event sent by diagnostics client.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.5
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information subscribers.
It is permitted only to an app signed by platform level certificates.
- Parameters:
-
[in] event_name Event name
Its length is limited to 255 characters + null terminator[in] client_id The ID of the diagnostics client (event sender)
Its length is limited to 255 characters + null terminator
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_INVALID_PARAMETER Provided parameter is invalid DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred DIAGNOSTICS_ERROR_OUT_OF_MEMORY Out of memory
int diagnostics_unset_data_request_cb | ( | void | ) |
Unsets the callback for diagnostics data request.
- Warning:
- This is not for use by third-party applications.
- Since :
- 6.5
- Privilege Level:
- platform
- Privilege:
- Remarks:
- This function is dedicated to diagnostic information providers.
It is permitted only to an app signed by platform level certificates.
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_PERMISSION_DENIED Permission denied DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred
int diagnostics_unset_notification_cb | ( | void | ) |
Unsets the callback for diagnostics event notification.
- Since :
- 6.0
- Remarks:
- This function is dedicated to diagnostic information subscribers.
It clears all the events added with diagnostics_subscribe_event().
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
DIAGNOSTICS_ERROR_NONE Success DIAGNOSTICS_ERROR_NOT_SUPPORTED Not supported DIAGNOSTICS_ERROR_IO_ERROR Internal error occurred