internals/docs/guides/inspections.md

   1 ## Tizen.Inspections Guide
   2
   3 `Tizen.Inspections` is used to collect data from applications and services. This API allows you to receive inspection events as well as request inspection data on demand (ex. receive crash reports if a process in the system crashes).
   4
   5 ## Prerequisites
   6
   7 Follow [get started](https://docs.tizen.org/application/dotnet/get-started/overview/) page to setup Visual Studio for .NET development.
   8
   9 To enable your application to use `Tizen.Inspections`:
  10
  11 1. To use `Tizen.Inspections` to collect inspectable data, the application must be signed with a platform level distributor certificate. Refer this [guide](https://docs.tizen.org/application/dotnet/tutorials/certificates/getting-the-certificates/) on how to sign an application with the custom certificate.
  12
  13 2. To use the methods and properties of the `Tizen.Inspections` namespace, include the namespace in your application::
  14
  15     ```c#
  16     Using Tizen.Inspections
  17     ```
  18
  19 ## Receive inspection events
  20
  21 `Tizen.Inspections` allows to receive status notification published by the platform (at future, Tizen inpsections will support to receive status notification published by manufacturer's applications).
  22
  23 In order to receive such notification, subscribe to the `EventReceived` event:
  24
  25 ```c#
  26 void callback(object sender, EventReceivedEventArgs e)
  27 {
  28     ...
  29 }
  30
  31 void getInspectableDataFromEvents()
  32 {
  33     Inspector.EventReceived += callback;
  34 }
  35 ```
  36
  37 When a new event arrives, callback is called. To read the inspection data out of the inspection context use `GetInspectableData()`:
  38
  39 ```c#
  40 void callback(object sender, EventReceivedEventArgs e)
  41 {
  42     if (e.Context.ModuleID == "org.tizen.system.crash")
  43     {
  44         string[] parameters = {"cs_info_json"};
  45         InspectionData data = e.Context.GetInspectableData(parameters);
  46     }
  47
  48     ...
  49 }
  50 ```
  51
  52 Use the `parameters` argument to specify which data to read from the inspection context. Available parameters depend on the module that provides the context.
  53
  54 In case of `"org.tizen.system.crash"` module, the proper values are:
  55
  56 -   `"cs_info_json"`: JSON report is returned, which contains information about crashed process such as callstack, mapped memory regions, and so on.
  57 -   `"cs_full"`: Full crash report ZIP archive is collected.
  58
  59 The obtained data is associated with the `data` Inspections handler. To read the data content, use `Read()` method:
  60
  61 ```c#
  62 void callback(object sender, EventReceivedEventArgs e)
  63 {
  64     if (e.Context.ModuleID == "org.tizen.system.crash")
  65     {
  66         string[] parameters = {"cs_info_json"};
  67         InspectionData data = e.Context.GetInspectableData(parameters);
  68
  69         byte[] buf = new byte[100];
  70         while (true)
  71         {
  72             // Read data and check for EOF
  73             if (data.Read(buf, 0, buf.Length) == 0)
  74                 break;
  75
  76             // Log received data
  77             Log.Info("InspectionsExample", System.Text.Encoding.UTF8.GetString(buf));
  78         }
  79     }
  80 }
  81 ```
  82
  83 ## Request diagnostic data
  84
  85 `Tizen.Inspections` can also request diagnostic data from other modules (applications or services).
  86
  87 For this purpose, call `RequestInspectableData()`. The `moduleId` parameter must be the id of the module that supports `Tizen.Inspections` requests:
  88
  89 ```c#
  90
  91 void requestInspectableData()
  92 {
  93     string moduleId = "org.tizen.some_service";
  94     string[] parameters = {"custom_parameter"};
  95
  96     InspectionData data = Inspector.RequestInspectableData(moduleId, parameters);
  97
  98     byte[] buf = new byte[100];
  99     while (true)
 100     {
 101         // Read data and check for EOF
 102         if (data.Read(buf, 0, buf.Length) == 0)
 103             break;
 104
 105         // Log received data
 106         Log.Info("InspectionsExample", System.Text.Encoding.UTF8.GetString(buf));
 107     }
 108 }
 109 ```
 110
 111 As in above example, after successful request, data may be read with `Read()` method.
 112
 113 ## Related information
 114 - Dependencies
 115   - Tizen 6.0 and Higher