docs/buxton_set_value.3

   1 '\" t
   2 .TH "BUXTON_SET_VALUE" "3" "buxton 1" "buxton_set_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_set_value, buxton_unset_value \- Modify values for BuxtonKeys
  24
  25 .SH "SYNOPSIS"
  26 .nf
  27 \fB
  28 #include <buxton.h>
  29 \fR
  30 .sp
  31 \fB
  32 int buxton_set_value(BuxtonClient \fIclient\fB,
  33 .br
  34                      BuxtonKey \fIkey\fB,
  35 .br
  36                      void *\fIvalue\fB,
  37 .br
  38                      BuxtonCallback \fIcallback\fB,
  39 .br
  40                      void *\fIdata\fB,
  41 .br
  42                      bool \fIsync\fB)
  43 .sp
  44 .br
  45 int buxton_unset_value(BuxtonClient \fIclient\fB,
  46 .br
  47                        BuxtonKey \fIkey\fB,
  48 .br
  49                        BuxtonCallback \fIcallback\fB,
  50 .br
  51                        void *\fIdata\fB,
  52 .br
  53                        bool \fIsync\fB)
  54 \fR
  55 .fi
  56
  57 .SH "DESCRIPTION"
  58 .PP
  59 These functions are used to modify values for a BuxtonKey, referenced
  60 by \fIkey\fR, on behalf of the \fIclient\fR.
  61
  62 To set the value for a \fIkey\fR, clients should call
  63 \fBbuxton_set_value\fR(3), passing a pointer the \fIvalue\fR for the
  64 third argument\&.
  65
  66 To unset the value for a \fIkey\fR, clients should call
  67 \fBbuxton_unset_value\fR(3)\&.
  68
  69 Both functions accept optional callback functions to register with
  70 the daemon, referenced by the \fIcallback\fR argument; the callback
  71 function is called upon completion of the operation\&. The \fIdata\fR
  72 argument is a pointer to arbitrary userdata that is passed along to
  73 the callback function\&. Additonally, the \fIsync\fR argument
  74 controls whether the operation should be synchronous or not; if
  75 \fIsync\fR is false, the operation is asynchronous\&.
  76
  77 .SH "CODE EXAMPLE"
  78 .PP
  79 An example for set_value:
  80
  81 .nf
  82 .sp
  83 #define _GNU_SOURCE
  84 #include <poll.h>
  85 #include <stdio.h>
  86 #include <stdlib.h>
  87 #include <string.h>
  88
  89 #include "buxton.h"
  90
  91 void set_cb(BuxtonResponse response, void *data)
  92 {
  93         BuxtonKey key;
  94         char *name;
  95
  96         if (buxton_response_status(response) != 0) {
  97                 printf("Failed to set value\\n");
  98                 return;
  99         }
 100
 101         key = buxton_response_key(response);
 102         name = buxton_key_get_name(key);
 103         printf("Set value for key %s\\n", name);
 104         buxton_key_free(key);
 105         free(name);
 106 }
 107
 108 int main(void)
 109 {
 110         BuxtonClient client;
 111         BuxtonKey key;
 112         struct pollfd pfd[1];
 113         int r;
 114         int fd;
 115         int32_t set;
 116
 117         if ((fd = buxton_open(&client)) < 0) {
 118                 printf("couldn't connect\\n");
 119                 return -1;
 120         }
 121
 122         key = buxton_key_create("hello", "test", "user", INT32);
 123         if (!key) {
 124                 return -1;
 125         }
 126
 127         set = 10;
 128
 129         if (buxton_set_value(client, key, &set, set_cb,
 130                              NULL, false)) {
 131                 printf("set call failed to run\\n");
 132                 return -1;
 133         }
 134
 135         pfd[0].fd = fd;
 136         pfd[0].events = POLLIN;
 137         pfd[0].revents = 0;
 138         r = poll(pfd, 1, 5000);
 139
 140         if (r <= 0) {
 141                 printf("poll error\\n");
 142                 return -1;
 143         }
 144
 145         if (!buxton_client_handle_response(client)) {
 146                 printf("bad response from daemon\\n");
 147                 return -1;
 148         }
 149
 150         buxton_key_free(key);
 151         buxton_close(client);
 152         return 0;
 153 }
 154 .fi
 155
 156 .PP
 157 An example for unset_value:
 158
 159 .nf
 160 .sp
 161 #define _GNU_SOURCE
 162 #include <poll.h>
 163 #include <stdio.h>
 164 #include <stdlib.h>
 165 #include <string.h>
 166
 167 #include "buxton.h"
 168
 169 void unset_cb(BuxtonResponse response, void *data)
 170 {
 171         if (buxton_response_status(response) != 0) {
 172                 printf("Failed to unset value\\n");
 173         } else {
 174                 printf("Unset value\\n");
 175         }
 176 }
 177
 178 int main(void)
 179 {
 180         BuxtonClient client;
 181         BuxtonKey key;
 182         struct pollfd pfd[1];
 183         int r;
 184         int fd;
 185
 186         if ((fd = buxton_open(&client)) < 0) {
 187                 printf("couldn't connect\\n");
 188                 return -1;
 189         }
 190
 191         key = buxton_key_create("hello", "test", "user", INT32);
 192         if (!key) {
 193                 return -1;
 194         }
 195
 196         if (buxton_unset_value(client, key, unset_cb,
 197                                NULL, false)) {
 198                 printf("unset call failed to run\\n");
 199                 return -1;
 200         }
 201
 202         pfd[0].fd = fd;
 203         pfd[0].events = POLLIN;
 204         pfd[0].revents = 0;
 205         r = poll(pfd, 1, 5000);
 206
 207         if (r <= 0) {
 208                 printf("poll error\\n");
 209                 return -1;
 210         }
 211
 212         if (!buxton_client_handle_response(client)) {
 213                 printf("bad response from daemon\\n");
 214                 return -1;
 215         }
 216
 217         buxton_key_free(key);
 218         buxton_close(client);
 219         return 0;
 220 }
 221 .fi
 222
 223 .SH "RETURN VALUE"
 224 .PP
 225 Returns 0 on success, and a non\-zero value on failure\&.
 226
 227 .SH "COPYRIGHT"
 228 .PP
 229 Copyright 2014 Intel Corporation\&. License: Creative Commons
 230 Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2, with exception
 231 for code examples found in the \fBCODE EXAMPLE\fR section, which are
 232 licensed under the MIT license provided in the \fIdocs/LICENSE.MIT\fR
 233 file from this buxton distribution\&.
 234
 235 .SH "SEE ALSO"
 236 .PP
 237 \fBbuxton\fR(7),
 238 \fBbuxtond\fR(8),
 239 \fBbuxton\-api\fR(7)
 240
 241 .SH "NOTES"
 242 .IP " 1." 4
 243 Creative Commons Attribution\-ShareAlike 3.0 Unported
 244 .RS 4
 245 \%http://creativecommons.org/licenses/by-sa/3.0/
 246 .RE