github.com/ubuntu/ubuntu-report@v1.7.4-0.20240410144652-96f37d845fac/pkg/sysmetrics/C/doc.go (about)

     1  // Package sysmetrics C bindings: collect and report system and hardware metrics
     2  // from your system.
     3  //
     4  // Collect system info
     5  //
     6  // Command signature:
     7  //   char* sysmetrics_collect(char** res);
     8  // "res" will be the pretty printed version of collected data. The return "err" will be != NULL in case
     9  // any error occurred during data collection.
    10  //
    11  // Example:
    12  //   #include <stdio.h>
    13  //   #include <stdlib.h>
    14  //   #include <libsysmetrics.h>
    15  //
    16  //   int main() {
    17  //       char *res, *err;
    18  //
    19  //       err = sysmetrics_collect(&res);
    20  //
    21  //       if (err != NULL) {
    22  //           printf("ERR: %s\n", err);
    23  //       } else {
    24  //           printf("GOT: %s\n", res);
    25  //       }
    26  //       free(res);
    27  //       free(err);
    28  //   }
    29  //
    30  // Send provided metrics data to server
    31  //
    32  // Command signature:
    33  //   char* sysmetrics_send_report(char* data, bool alwaysReport, char* baseUrl);
    34  //
    35  // The report will not be sent if a report has already been sent for this version unless "alwaysReport" is true.
    36  // If "baseURL" is not an empty string, this overrides the server the report is sent to.
    37  // The return "err" will be != NULL in case any error occurred during POST.
    38  //
    39  // Example (sending provided metrics data):
    40  //   #include <stdbool.h>
    41  //   #include <stdio.h>
    42  //   #include <stdlib.h>
    43  //   #include <libsysmetrics.h>
    44  //
    45  //   int main() {
    46  //       char *err;
    47  //
    48  //       err = sysmetrics_send_report("{ \"Version\": \"18.04\" }", false, "");
    49  //
    50  //       if (err != NULL) {
    51  //           printf("ERR: %s\n", err);
    52  //       } else {
    53  //           printf("Report sent to default server");
    54  //       }
    55  //       free(err);
    56  //   }
    57  //
    58  // Send denial message to server
    59  //
    60  // Command signature:
    61  //   char* sysmetrics_send_decline(bool alwaysReport, char* baseUrl);
    62  //
    63  // The denial message will not be sent if a report has already been sent for this version unless "alwaysReport" is true.
    64  // If "baseURL" is not an empty string, this overrides the server the report is sent to.
    65  // The return "err" will be != NULL in case any error occurred during POST.
    66  //
    67  // Example:
    68  //   #include <stdbool.h>
    69  //   #include <stdio.h>
    70  //   #include <stdlib.h>
    71  //   #include <libsysmetrics.h>
    72  //
    73  //   int main() {
    74  //       char *err;
    75  //
    76  //       err = sysmetrics_send_decline(false, "");
    77  //
    78  //       if (err != NULL) {
    79  //           printf("ERR: %s\n", err);
    80  //       } else {
    81  //           printf("Decline sent to default server");
    82  //       }
    83  //       free(err);
    84  //   }
    85  //
    86  // Collect and send system info to server
    87  //
    88  // Command signature:
    89  //   char* sysmetrics_collect_and_send(sysmetrics_report_type r, bool alwaysReport, char* url);
    90  //
    91  // sysmetrics_report_type is the following enum:
    92  //    typedef enum {
    93  //      // sysmetrics_report_interactive will show report content on stdout and read anwser on stdin
    94  //      sysmetrics_report_interactive = 0,
    95  //      // sysmetrics_report_auto will send a report without printing report
    96  //      sysmetrics_report_auto = 1,
    97  //      // sysmetrics_report_optout will send opt-out message without printing report
    98  //      sysmetrics_report_optout = 2,
    99  //    } sysmetrics_report_type;
   100  // You should generally prefer in bindings the auto or optout report. Interactive is based on stdout and stdin.
   101  // The report will not be sent if a report has already been sent for this version unless "alwaysReport" is true.
   102  // It can be sent to an alternative url via "baseURL" to send the report to. Empty string will send to default server.
   103  //
   104  // Example (in autoreport mode, without reporting twice the same data and using default server URL):
   105  //   #include <stdbool.h>
   106  //   #include <stdio.h>
   107  //   #include <stdlib.h>
   108  //   #include <libsysmetrics.h>
   109  //
   110  //   int main() {
   111  //       sysmetrics_report_type r = sysmetrics_report_auto;
   112  //       char *err;
   113  //
   114  //       err = sysmetrics_collect_and_send(r, false, "");
   115  //
   116  //       if (err != NULL) {
   117  //           printf("ERR: %s\n", err);
   118  //       } else {
   119  //           printf("Report sent to default server");
   120  //       }
   121  //       free(err);
   122  //   }
   123  //
   124  // Building as a shared library
   125  //
   126  // The following command (in the pkg/sysmetrics/C directory) will provide a .h and .so file:
   127  //   go build -o libsysmetrics.so.1 -buildmode=c-shared -ldflags '-extldflags -Wl,-soname,libsysmetrics.so.1' libsysmetrics.go
   128  // You will probably want to rename libsysmetrics.so.h to libsysmetrics.h. Note that go generate will proceed
   129  // this for you.
   130  //
   131  // Then, you can simply build your example program with:
   132  //   gcc main.c ./libsysmetrics.so.1
   133  //
   134  package main