docs/buxton_get_value.3

   1 '\" t
   2 .TH "BUXTON_GET_VALUE" "3" "buxton 1" "buxton_get_value"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 buxton_get_value \- Get the value of a key\-name
  24
  25 .SH "SYNOPSIS"
  26 .nf
  27 \fB
  28 #include <buxton.h>
  29 \fR
  30 .sp
  31 \fB
  32 int buxton_get_value(BuxtonClient \fIclient\fB,
  33 .br
  34                      BuxtonKey \fIkey\fB,
  35 .br
  36                      BuxtonCallback \fIcallback\fB,
  37 .br
  38                      void *\fIdata\fB,
  39 .br
  40                      bool \fIsync\fB)
  41 \fR
  42 .fi
  43
  44 .SH "DESCRIPTION"
  45 .PP
  46 This function is used to get the value of a key\-name for
  47 \fIclient\fR. The key\-name is referenced by \fIkey\fR. If the layer
  48 for \fIkey\fR is NULL, buxton will traverse layers in priority order
  49 searching for the key-name value, selecting the value for the first
  50 key\-name found\&. If the argument is non-NULL, the operation will
  51 target only that layer\&. For more information on creating a
  52 BuxtonKey to pass for \fIkey\fR, see \fBbuxton_key_create\fR(3)\&.
  53
  54 To retrieve the result of the operation, clients should define a
  55 callback function, referenced by the \fIcallback\fR argument; the
  56 callback function is called upon completion of the operation\&. The
  57 \fIdata\fR argument is a pointer to arbitrary userdata that is passed
  58 along to the callback function\&. Additonally, the \fIsync\fR
  59 argument controls whether the operation should be synchronous or not;
  60 if \fIsync\fR is false, the operation is asynchronous\&.
  61
  62 .SH "CODE EXAMPLE"
  63 .nf
  64 .sp
  65 #define _GNU_SOURCE
  66 #include <poll.h>
  67 #include <stdio.h>
  68 #include <stdlib.h>
  69 #include <string.h>
  70
  71 #include "buxton.h"
  72
  73 void get_cb(BuxtonResponse response, void *data)
  74 {
  75         int32_t* ret = (int32_t*)data;
  76
  77         if (buxton_response_status(response) != 0) {
  78                 printf("Failed to get value\\n");
  79                 return;
  80         }
  81
  82         *ret = *(int32_t*)buxton_response_value(response);
  83 }
  84
  85 int main(void)
  86 {
  87         BuxtonClient client;
  88         BuxtonKey key;
  89         struct pollfd pfd[1];
  90         int r;
  91         int32_t gvalue = -1;
  92         int fd;
  93
  94         if ((fd = buxton_open(&client)) < 0) {
  95                 printf("couldn't connect\\n");
  96                 return -1;
  97         }
  98
  99         key = buxton_key_create("hello", "test", "user", INT32);
 100         if (!key) {
 101                 return -1;
 102         }
 103
 104         if (buxton_get_value(client, key, get_cb,
 105                              &gvalue, false)) {
 106                 printf("get call failed to run\\n");
 107                 return -1;
 108         }
 109
 110         pfd[0].fd = fd;
 111         pfd[0].events = POLLIN;
 112         pfd[0].revents = 0;
 113         r = poll(pfd, 1, 5000);
 114
 115         if (r <= 0) {
 116                 printf("poll error\\n");
 117                 return -1;
 118         }
 119
 120         if (!buxton_client_handle_response(client)) {
 121                 printf("bad response from daemon\\n");
 122                 return -1;
 123         }
 124
 125         if (gvalue >= 0) {
 126                 printf("got value: %d\\n", gvalue);
 127         }
 128
 129         buxton_key_free(key);
 130         buxton_close(client);
 131         return 0;
 132 }
 133 .fi
 134
 135 .SH "RETURN VALUE"
 136 .PP
 137 Returns 0 on success, and a non\-zero value on failure\&.
 138
 139 .SH "COPYRIGHT"
 140 .PP
 141 Copyright 2014 Intel Corporation\&. License: Creative Commons
 142 Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2, with exception
 143 for code examples found in the \fBCODE EXAMPLE\fR section, which are
 144 licensed under the MIT license provided in the \fIdocs/LICENSE.MIT\fR
 145 file from this buxton distribution\&.
 146
 147 .SH "SEE ALSO"
 148 .PP
 149 \fBbuxton\fR(7),
 150 \fBbuxtond\fR(8),
 151 \fBbuxton\-api\fR(7)
 152
 153 .SH "NOTES"
 154 .IP " 1." 4
 155 Creative Commons Attribution\-ShareAlike 3.0 Unported
 156 .RS 4
 157 \%http://creativecommons.org/licenses/by-sa/3.0/
 158 .RE