Tizen Native API  7.0
Diagnostics

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]ctxDiagnostics context handle
[in]user_dataThe 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]dataDiagnostics data handle
[in]paramsArray 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_sizeNumber of parameters
[in]ctxDiagnostics 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_dataThe user data passed from the callback registration function

Enumeration Type Documentation

Enumeration for error codes of Diagnostics.

Since :
6.0
Enumerator:
DIAGNOSTICS_ERROR_NONE 

Successful

DIAGNOSTICS_ERROR_INVALID_PARAMETER 

Invalid parameter

DIAGNOSTICS_ERROR_IO_ERROR 

I/O error

DIAGNOSTICS_ERROR_OUT_OF_MEMORY 

Out of memory

DIAGNOSTICS_ERROR_RESOURCE_BUSY 

Device or resource busy

DIAGNOSTICS_ERROR_TIMED_OUT 

Time out

DIAGNOSTICS_ERROR_NOT_SUPPORTED 

Not supported

DIAGNOSTICS_ERROR_TRY_AGAIN 

Try again

DIAGNOSTICS_ERROR_PERMISSION_DENIED 

Permission denied


Function Documentation

Frees diagnostics data.

Since :
6.0
Parameters:
[in]dataDiagnostics data handle
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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]dataDiagnostics data handle
[in,out]fdA file descriptor related to diagnostics data
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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]dataDiagnostics data handle
[in,out]bufBuffer to store read data
Provided buffer must be large enough to contain a count number of bytes
[in]countNumber of bytes to read
[in]timeout_msTimeout [ms] for reading requested number of bytes (timeout_ms <= 0 means to wait forever)
[out]bytes_readReal number of bytes read
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_TIMED_OUTTimeout occurred
DIAGNOSTICS_ERROR_TRY_AGAINTry again
DIAGNOSTICS_ERROR_IO_ERRORInternal 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]dataDiagnostics data handle
[in]bufBuffer with data to write
Provided buffer must be of size not less than a count number of bytes
[in]countNumber of bytes to write
[out]bytes_writtenReal number of bytes written
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_TRY_AGAINTry again
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred while trying to write data, result is unspecified and *bytes_written is not updated

Frees diagnostics context.

Since :
6.0
Parameters:
[in]ctxDiagnostics context handle
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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]ctxDiagnostics context handle
[out]client_idID of the diagnostics client
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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]ctxDiagnostics context handle
[in]paramsArray of parameters
Refer to specific diagnostics client's documentation for available parameters
[in]params_sizeNumber of parameters
[out]dataDiagnostics data handle
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred
DIAGNOSTICS_ERROR_OUT_OF_MEMORYNot 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]ctxDiagnostics context handle
[out]event_dataData 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_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDDiagnostics feature is missing or the function has been called by application, not system service
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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]ctxDiagnostics context handle
[out]event_nameName of the diagnostics event
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided 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);
 }

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]pidID 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_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid or the caller ID not set (required for system services only)
DIAGNOSTICS_ERROR_IO_ERRORInternal 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_idAn ID of application or service to request
[in]paramsArray of parameters
Refer to specific diagnostics client's documentation for available parameters
[in]params_sizeNumber of parameters
[out]dataDumpsys data handle
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred
DIAGNOSTICS_ERROR_OUT_OF_MEMORYNot 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_nameDiagnostics event name
[in]event_dataEvent data or NULL.
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid or the caller ID not set (required for system services only)
DIAGNOSTICS_ERROR_IO_ERRORInternal 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_idDiagnostics client ID to set.
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_RESOURCE_BUSYClient ID has already been set, not possible to change
DIAGNOSTICS_ERROR_IO_ERRORInternal 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]callbackA callback function to set
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid or the caller ID not set (required for system services only)
DIAGNOSTICS_ERROR_RESOURCE_BUSYCallback already registered
DIAGNOSTICS_ERROR_IO_ERRORInternal 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]callbackA callback function to set
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
DIAGNOSTICS_ERROR_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_RESOURCE_BUSYCallback already registered
DIAGNOSTICS_ERROR_IO_ERRORInternal 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_nameEvent name
Its length is limited to 255 characters + null terminator
[in]client_idThe 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_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_INVALID_PARAMETERProvided parameter is invalid
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred
DIAGNOSTICS_ERROR_OUT_OF_MEMORYOut of memory

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_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_PERMISSION_DENIEDPermission denied
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred

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_NONESuccess
DIAGNOSTICS_ERROR_NOT_SUPPORTEDNot supported
DIAGNOSTICS_ERROR_IO_ERRORInternal error occurred