docs/buxton_create_group.3

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