src/libpwmd.h.in

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2009 Ben Kibbey <bjk@luxsci.net>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  18 */
  19 /*! \headerfile libpwmd.h
  20  *
  21  * libpwmd is a library making it easy for applications to use the pwmd
  22  * server.
  23  */
  24
  25 /*! \section ssh SSH Details
  26  *
  27  * \todo
  28  */
  29
  30 /*! \section pinentry Pinentry Details
  31  *
  32  * \todo
  33  */
  34
  35 /*! \section example Example Client
  36  *
  37  * The following example will list the element tree of the data file specified
  38  * in the first command line argument.
  39  *
  40  * \code
  41  * #include <stdio.h>
  42  * #include <libpwmd.h>
  43  *
  44  * int main()
  45  * {
  46  *     pwm_t *pwm = pwmd_new(NULL);
  47  *     gpg_error_t rc = pwmd_connect(pwm, NULL);
  48  *     char *result;
  49  *
  50  *     if (!rc) {
  51  *         rc = pwmd_open(pwm, argv[1]);
  52  *
  53  *         if (!rc) {
  54  *             rc = pwmd_command(pwm, &result, "%s", "LIST");
  55  *
  56  *             if (!rc) {
  57  *                 printf("%s", result);
  58  *                 pwmd_free(result);
  59  *             }
  60  *         }
  61  *     }
  62  *
  63  *     pwmd_close(pwm);
  64  *
  65  *     if (rc)
  66  *         fprintf(stderr, "ERR: %s\n", pwmd_strerror(rc));
  67  *
  68  *     exit(rc ? 1 : 0);
  69  * }
  70  * \endcode
  71  */
  72
  73 /*! \file */
  74 #ifndef LIBPWMD_H
  75 #define LIBPWMD_H
  76
  77 #include <gpg-error.h>
  78 #include <stdarg.h>
  79
  80 #ifdef __cplusplus
  81 extern "C" {
  82 #endif
  83
  84 /*! \def LIBPWMD_VERSION
  85  *  \hideinitializer
  86  *
  87  * The version of this library.
  88  */
  89 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_COMPAT@@VER_PATCH@
  90
  91
  92 struct pwm_s;
  93 /*! \typedef pwm_t
  94  *
  95  * When a handle is mentioned in this documentation it is a pointer of this
  96  * type. A new handle is created with \ref pwmd_new().
  97  */
  98 typedef struct pwm_s pwm_t;
  99
 100
 101 /*! \typedef pwmd_async_t
 102  *
 103  * The return code of \ref pwmd_process() which is used for all asynchronous
 104  * commands.
 105  */
 106 typedef enum {
 107     /*! \internal */
 108     ASYNC_INIT,
 109
 110     /*! \ref pwmd_process() should be called again. */
 111     ASYNC_PROCESS,
 112
 113     /*! The command has completed. The result code should be checked for an
 114      * error. */
 115     ASYNC_DONE,
 116 } pwmd_async_t;
 117
 118
 119 /*! \typedef pwmd_ip_version_t
 120  *
 121  * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
 122  * pwmd_setopt().
 123  */
 124 typedef enum {
 125     /*! Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. */
 126     PWMD_IP_ANY,
 127
 128     /*! Only try IPv4. */
 129     PWMD_IPV4,
 130
 131     /*! Only try IPv6. */
 132     PWMD_IPV6
 133 } pwmd_ip_version_t;
 134
 135
 136 /*! \typedef pwmd_passphrase_cb_t
 137  *
 138  * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
 139  * \ref pwmd_setopt().
 140  *
 141  * \param user A user data pointer which is set with \ref
 142  * PWMD_OPTION_PASSPHRASE_DATA.
 143  * \param[out] passphrase The passphrase which may be an empty string or NULL.
 144  * \return 0 on success or an error code which will cause a command to fail.
 145  */
 146 typedef gpg_error_t (*pwmd_passphrase_cb_t)(void *user, char **passphrase);
 147
 148
 149 /*! \typedef pwmd_status_cb_t
 150  *
 151  * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 152  * pwmd_setopt().
 153  *
 154  * \param user A user data pointer which is set with \ref
 155  * PWMD_OPTION_STATUS_DATA.
 156  * \param line The status message line.
 157  * \return 0 on success or an error code which will cause a command to fail.
 158  */
 159 typedef int (*pwmd_status_cb_t)(void *user, const char *line);
 160
 161
 162 /*! \typedef pwmd_inquire_cb_t
 163  *
 164  * This is a callback function that gets passed to \ref pwmd_inquire(). It is
 165  * used for sending data to the server for commands that return an INQUIRE
 166  * response (STORE and IMPORT). The reason for this callback is to let the
 167  * client send as many bytes as it wants rather than the entire chunk at once.
 168  * It gets called during \ref assuan_transact() from an internal inquire
 169  * callback function which in turn calls this function by looping over its
 170  * return value.
 171  *
 172  * \param user The user data pointer passed to \ref pwmd_inquire().
 173  * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
 174  * \param rc The result of the last internal call to \ref assuan_send_data()
 175  * which did the sending of the data to the pwmd server. On the first call to
 176  * this callback it will always be 0 because no data has been sent yet.
 177  * \param[out] data The next chunk of data to send or NULL.
 178  * \param[out] len The length of \a data or 0.
 179  *
 180  * \retval 0 There is more data to be sent.
 181  * \retval GPG_ERR_EOF No need to call this function again, the current
 182  * \a line is the last to send.
 183  * \retval code Any other error code which will terminate the INQUIRE.
 184  *
 185  * \note The sent data is processed line-per-line. The line is either newline
 186  * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 187  * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 188  */
 189 typedef gpg_error_t (*pwmd_inquire_cb_t)(void *user, const char *cmd,
 190         gpg_error_t rc, char **data, size_t *len);
 191
 192
 193 /*! \enum pwmd_option_t
 194  *
 195  * libpwmd options which are set with \ref pwmd_setopt().
 196  */
 197 typedef enum {
 198     /*! A custom passphrase retrieval function which, when set, will be used
 199      * instead of \ref pinentry(1). This function will not be used when the
 200      * passphrase is cached on the server or the file is a new one. The value
 201      * of this option should be a \ref pwmd_passphrase_cb_t function pointer.
 202      */
 203     PWMD_OPTION_PASSPHRASE_CB,
 204
 205     /*! User supplied data which is passed to the custom password function. */
 206     PWMD_OPTION_PASSPHRASE_DATA,
 207
 208     /*! An integer value that specifies the specified the number of tries
 209      * before \ref pinentry(1) will give up when opening a file with the wrong
 210      * supplied passphrase. The default is 3.
 211      *
 212      * \note This option has no effect when trying to save a file. The user
 213      * must either cancel the pinentry causing the save to fail or enter the
 214      * correct passphrase during passphrase confirmation.
 215      */
 216     PWMD_OPTION_PINENTRY_TRIES,
 217
 218     /*! A character string value which specifies the full path of the \ref
 219      * pinentry(1) binary. For the local \ref pinentry(1) method, the default
 220      * is specified at compile time.
 221      */
 222     PWMD_OPTION_PINENTRY_PATH,
 223
 224     /*! A value which specifies the full path to the tty that \ref pinentry(1)
 225      * will use. When set and no DISPLAY is available, \ref
 226      * PWMD_OPTION_PINENTRY_TERM must also be set.
 227      *
 228      * \see \ref pinentry
 229      */
 230     PWMD_OPTION_PINENTRY_TTY,
 231
 232     /*! A value which specifies the X11 display that \ref pinentry(1) will
 233      * use.
 234      *
 235      * \see \ref pinentry
 236      */
 237     PWMD_OPTION_PINENTRY_DISPLAY,
 238
 239     /*! A value which specifies the terminal type (e.g., vt100) that \ref
 240      * pinentry(1) will use when no X11 display is available.
 241      *
 242      * \see \ref pinentry
 243      */
 244     PWMD_OPTION_PINENTRY_TERM,
 245
 246     /*! A string to use as the passphrase when doing an open or save. When not
 247      * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
 248      */
 249     PWMD_OPTION_PASSPHRASE,
 250
 251     /*! A character string that \ref pinentry(1) will use in it's dialog
 252      * window.
 253      */
 254     PWMD_OPTION_PINENTRY_TITLE,
 255
 256     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 257     PWMD_OPTION_PINENTRY_PROMPT,
 258
 259     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 260     PWMD_OPTION_PINENTRY_DESC,
 261
 262     /*! For \ref pinentry(1) localization. */
 263     PWMD_OPTION_PINENTRY_LC_CTYPE,
 264
 265     /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
 266     PWMD_OPTION_PINENTRY_LC_MESSAGES,
 267
 268     /*! An integer value that specifies the number of seconds \ref pinentry(1)
 269      * will wait for input before timing out and aborting the current command.
 270      * If 0, then no timeout will be used. The default is 30.
 271      */
 272     PWMD_OPTION_PINENTRY_TIMEOUT,
 273
 274     /*! A function pointer of type \ref pwmd_status_cb_t that will process
 275      * status messages received from the pwmd server.
 276      */
 277     PWMD_OPTION_STATUS_CB,
 278
 279     /*! A user data pointer which is passed to the status message function. */
 280     PWMD_OPTION_STATUS_DATA,
 281
 282     /*! The IP version of type \ref pwmd_ip_version_t that \ref
 283      * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
 284      * connecting to the remote pwmd server.
 285      *
 286      * \pre_conn_req
 287      */
 288     PWMD_OPTION_IP_VERSION,
 289 } pwmd_option_t;
 290
 291
 292 /*! \brief Initialize the library.
 293  *
 294  * This function must be the first function called in the library before any
 295  * others. It sets up internationalization among other things.
 296  *
 297  * \return 0 Success.
 298  */
 299 gpg_error_t pwmd_init(void);
 300
 301
 302 /*! \brief Creates a new handle.
 303  *
 304  * Creates a new handle for use with the other functions.
 305  *
 306  * \param name If not NULL, the name of the application. The application name
 307  * is sent to the pwmd server after successfully connecting.
 308  *
 309  * \param name The application name or NULL.
 310  * \return a new handle or NULL if there was not enough memory.
 311  */
 312 pwm_t *pwmd_new(const char *name)
 313     __attribute__ ((warn_unused_result));
 314
 315
 316 /*! \brief Connect to a local pwmd server.
 317  *
 318  * Connects to a local unix domain socket.
 319  *
 320  * \param pwm A handle.
 321  * \param path The socket path to connect to. If NULL, then a default of
 322  * \a "~/.pwmd/socket" will be used.
 323  * \return 0 on success or an error code.
 324  * \see pwmd_ssh_connect(), pwmd_ssh_connect_async()
 325  */
 326 gpg_error_t pwmd_connect(pwm_t *pwm, const char *path)
 327     __attribute__ ((warn_unused_result));
 328
 329
 330 /*! \brief Establish a remote connection to a pwmd server.
 331  *
 332  * Connects to a pwmd server over an SSH channel.
 333  *
 334  * \param pwm A handle.
 335  * \param host The hostname to connect to.
 336  * \param port The port or -1 for the default.
 337  * \param identity The SSH identity to use for authentication.
 338  * \param user The username on the SSH server to login as. If NULL then
 339  * invoking user will be used.
 340  * \param known_hosts A file containing the public SSH server key hash in SHA1
 341  * format.
 342  * \return 0 on success or an error code.
 343  * \see pwmd_ssh_connect_async(), pwmd_process(), \ref ssh
 344  * \todo X11 forwarding.
 345  */
 346 gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port,
 347         const char *identity, const char *user, const char *known_hosts)
 348     __attribute__ ((warn_unused_result));
 349
 350
 351 /*! \brief Establish a remote connection to a pwmd server asynchronously.
 352  *
 353  * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
 354  * DNS lookups or while connecting.
 355  *
 356  * \ref pwmd_process() should be called until the command completes.
 357  *
 358  * \param pwm A handle.
 359  * \param host The hostname to connect to.
 360  * \param port The port or -1 for the default.
 361  * \param identity The SSH identity to use for authentication.
 362  * \param user The username on the SSH server to login as. If NULL, the
 363  * invoking username will be used.
 364  * \param known_hosts A file containing the public SSH server key hash in SHA1
 365  * format.
 366  * \return 0 on success or an error code.
 367  * \see pwmd_process(), \ref ssh
 368  * \todo X11 forwarding.
 369  */
 370 gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host, int port,
 371         const char *identity, const char *user, const char *known_hosts)
 372     __attribute__ ((warn_unused_result));
 373
 374
 375 /*! \brief Retrieve a remote SSH host key.
 376  *
 377  * This key is needed for host verification of the remote pwmd server.
 378  *
 379  * \param pwm A handle.
 380  * \param host The hostname to connect to.
 381  * \param port The port.
 382  * \param[out] result The server host key which must be freed with \ref
 383  * pwmd_free().
 384  * \return 0 on success or an error code.
 385  * \see pwmd_get_hostkey_async(), \ref ssh
 386  */
 387 gpg_error_t pwmd_get_hostkey(pwm_t *pwm, const char *host, int port,
 388         char **result)
 389     __attribute__ ((warn_unused_result));
 390
 391
 392 /*! \brief Retrieve a remote SSH host key asynchronously.
 393  *
 394  * This key is needed for host verification of the remote pwmd server.
 395  *
 396  * \ref pwmd_process() should be called until the command completes.
 397  *
 398  * \param pwm A handle.
 399  * \param host The hostname to connect to.
 400  * \param port The port or a default if set to -1.
 401  * \return 0 on success or an error code.
 402  * \see pwmd_get_hostkey(), \ref ssh
 403  */
 404 gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host, int port)
 405     __attribute__ ((warn_unused_result));
 406
 407
 408 /*! \brief Get the socket file descriptor.
 409  *
 410  * This will allow polling of the file descriptor associated with the assuan
 411  * context and in turn the pwmd server. It can be used to determine whether
 412  * \ref pwmd_process() should be called to process status messages.
 413  *
 414  * \param pwm A handle.
 415  * \param[out] fd Set to the file descriptor of the associated handle.
 416  * \return 0 on success or an error code.
 417  * \see pwmd_process()
 418  */
 419 gpg_error_t pwmd_get_fd(pwm_t *pwm, int *fd)
 420     __attribute__ ((warn_unused_result));
 421
 422
 423 /*! \brief Get the file descriptor of the local pinentry method.
 424  *
 425  * This will allow polling of the file descriptor associated with the pipe of
 426  * the forked pinentry process from \ref pwmd_open_async2() and \ref
 427  * pwmd_save_async2().
 428  *
 429  * \param pwm A handle.
 430  * \param[out] fd Set to the file descriptor of the associated handle.
 431  * \return 0 on success or an error code.
 432  * \see pwmd_process(), pwmd_open_async2(), pwmd_save_async2()
 433  */
 434 gpg_error_t pwmd_get_async2_fd(pwm_t *pwm, int *fd)
 435     __attribute__ ((warn_unused_result));
 436
 437
 438 /*! \brief Check for a unparsed buffered line.
 439  *
 440  * A buffered line is a line that was read from the server but was not
 441  * processed. This function determines if there is such a line.
 442  *
 443  * \param pwm A handle.
 444  * \retval 0 if there is pending data.
 445  * \retval GPG_ERR_NO_DATA if there is no pending data.
 446  * \see pwmd_process()
 447  */
 448 gpg_error_t pwmd_pending_line(pwm_t *pwm)
 449     __attribute__ ((warn_unused_result));
 450
 451
 452 /*! \brief Set library options.
 453  *
 454  * See \ref pwmd_option_t for option specific details.
 455  *
 456  * \param pwm A handle.
 457  * \param opt The option.
 458  * \param ... The option value.
 459  * \return 0 on success or an error code.
 460  */
 461 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...)
 462     __attribute__ ((warn_unused_result));
 463
 464
 465 /*! \brief Open a file on the pwmd server.
 466  *
 467  * This will send the OPEN command to the server.
 468  *
 469  * \param pwm A handle.
 470  * \param filename The filename to open.
 471  * \return 0 on success or an error code.
 472  * \see \ref pinentry
 473  */
 474 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename)
 475     __attribute__ ((warn_unused_result));
 476
 477 /*! \brief Open a file on the pwmd server using a local pinentry.
 478  *
 479  * This will send the OPEN command to the server like \ref pwmd_open() but
 480  * will use the local pinentry and not pwmd's pinentry.
 481  *
 482  * \param pwm A handle.
 483  * \param filename The filename to open.
 484  * \return 0 on success or an error code.
 485  * \see \ref pinentry
 486  */
 487 gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename)
 488     __attribute__ ((warn_unused_result));
 489
 490
 491 /*! \brief Open a file on the pwmd server asynchronously (fork method).
 492  *
 493  * This will send the OPEN command to the pwmd server. The difference from
 494  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 495  * passphrase input.
 496  *
 497  * The difference from \ref pwmd_open_async() is that libpwmd will \ref fork()
 498  * a pinentry process rather than have pwmd use it's pinentry method. This may
 499  * be useful if the passphrase isn't cached on a remote pwmd server and a
 500  * remote \ref pinentry(1) is not possible.
 501  *
 502  * \ref pwmd_process() should be called until the command completes.
 503  *
 504  * \param pwm A handle.
 505  * \param filename The filename to open.
 506  * \return 0 on success or an error code.
 507  * \see pwmd_process(), \ref pinentry
 508  */
 509 gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename)
 510     __attribute__ ((warn_unused_result));
 511
 512
 513 /*! \brief Open a file on the pwmd server asynchronously.
 514  *
 515  * This will send the OPEN command to the pwmd server. The difference from
 516  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 517  * passphrase input.
 518  *
 519  * \ref pwmd_process() should be called until the command completes.
 520  *
 521  * \param pwm A handle.
 522  * \param filename The filename to open.
 523  * \return 0 on success or an error code.
 524  * \see pwmd_process(), \ref pinentry
 525  */
 526 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename)
 527     __attribute__ ((warn_unused_result));
 528
 529
 530 /*! \brief Process an asynchronous function.
 531  *
 532  * After an asynchronous function has been called and has returned
 533  * successfully, this function must be called to process the command to
 534  * retrieve the result or return value.
 535  *
 536  * This function may also be called when not in a command to check for pending
 537  * status messages sent from the server or to process a pending line.
 538  *
 539  * \param pwm A handle.
 540  * \param rc Set to the return code of the command after ASYNC_DONE is
 541  * returned. This value must be checked to determine if the command succeeded.
 542  * \param[out] result Set to the result of the command when \a rc is 0. Note
 543  * that not all commands return a result.
 544  * \retval ASYNC_DONE The command has completed. \a rc should be checked to
 545  * determine if the command was successful or not.
 546  * \retval ASYNC_PROCESS The command is still running and this function should
 547  * be called again.
 548  * \see pwmd_get_fd(), pwmd_get_fd2(), pwmd_pending_line()
 549  */
 550 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result)
 551     __attribute__ ((warn_unused_result));
 552
 553
 554 /*! \brief Save a file on the pwmd server.
 555  *
 556  * This will send the SAVE command.
 557  *
 558  * \param pwm A handle.
 559  * \return 0 on success or an error code.
 560  * \see \ref pinentry
 561  */
 562 gpg_error_t pwmd_save(pwm_t *pwm)
 563     __attribute__ ((warn_unused_result));
 564
 565
 566 /*! \brief Save a file on the pwmd server using the local pinentry.
 567  *
 568  * This will send the SAVE command like \ref pwmd_save() but will use a local
 569  * pinentry and not pwmd's pinentry.
 570  *
 571  * \param pwm A handle.
 572  * \return 0 on success or an error code.
 573  * \see \ref pinentry
 574  */
 575 gpg_error_t pwmd_save2(pwm_t *pwm)
 576     __attribute__ ((warn_unused_result));
 577
 578
 579 /*! \brief Save a file on the pwmd server asynchronously (fork method).
 580  *
 581  * This will send the SAVE command to the pwmd server. The difference from
 582  * \ref pwmd_save() is that it will not block if a pinentry is needed for
 583  * passphrase input.
 584  *
 585  * The difference from \ref pwmd_save_async() is that libpwmd will \ref fork()
 586  * a pinentry process rather than have pwmd use it's pinentry method. This may
 587  * be useful if the passphrase isn't cached on a remote pwmd server and a
 588  * remote \ref pinentry(1) is not possible.
 589  *
 590  * \ref pwmd_process() should be called until the command completes.
 591  *
 592  * \param pwm A handle.
 593  * \return 0 on success or an error code.
 594  * \see pwmd_process(), \ref pinentry
 595  */
 596 gpg_error_t pwmd_save_async2(pwm_t *pwm)
 597     __attribute__ ((warn_unused_result));
 598
 599
 600 /*! \brief Save changes to a file on the pwmd server asynchronously.
 601  *
 602  * This will send the SAVE command to the pwmd server. The difference from
 603  * \ref pwmd_save() is that it will not block if a pinentry is needed for
 604  * passphrase input.
 605  *
 606  * \ref pwmd_process() should be called until the command completes.
 607  *
 608  * \param pwm A handle.
 609  * \return 0 on success or an error code.
 610  * \see pwmd_process(), \ref pinentry
 611  */
 612 gpg_error_t pwmd_save_async(pwm_t *pwm)
 613     __attribute__ ((warn_unused_result));
 614
 615
 616 /*! \brief Send a command to the pwmd server.
 617  *
 618  * Sends a command to the pwmd server. You should avoid sending the BYE
 619  * command here because the assuan context will be freed and bad things will
 620  * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
 621  * send data to the server (STORE and IMPORT), \ref pwmd_inquire() should be
 622  * used and not this function.
 623  *
 624  * \param pwm A handle.
 625  * \param[out] result The result of the command when successful and which must
 626  * be freed with \ref pwmd_free(). Note that not all commands return a result.
 627  * \param cmd The command to send.
 628  * \param ... The arguments to \a cmd.
 629  * \return 0 on success or an error code.
 630  */
 631 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...)
 632     __attribute__ ((warn_unused_result));
 633
 634
 635 /*! \brief Send a command to the pwmd server.
 636  *
 637  * Like \ref pwmd_command() but uses an argument pointer instead.
 638  *
 639  * \param pwm A handle.
 640  * \param[out] result The result of the command when successful which must be
 641  * freed with \ref pwmd_free(). Note that not all commands return a result.
 642  * \param cmd The command to send.
 643  * \param ap The arguments to \a cmd.
 644  * \return 0 on success or an error code.
 645  */
 646 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 647         va_list ap)
 648     __attribute__ ((warn_unused_result));
 649
 650
 651 /*! \brief Send data to a pwmd server.
 652  *
 653  * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
 654  * to the server. Use this function rather than \ref pwmd_command() for these
 655  * commands.
 656  *
 657  * \param pwm A handle.
 658  * \param cmd The command to send that uses an INQUIRE.
 659  * \param func A callback function which sets the data to be sent.
 660  * \param user A user data pointer passed to the callback function \a func.
 661  * \return 0 on success or an error code.
 662  *
 663  * \see pwmd_inquire_cb_t
 664  */
 665 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_cb_t func,
 666         void *user)
 667     __attribute__ ((warn_unused_result));
 668
 669
 670 /*! \brief Close a handle.
 671  *
 672  * This will close the connection to a pwmd server and free any resources
 673  * associated with it.
 674  *
 675  * \param pwm A handle.
 676  * \return Nothing.
 677  */
 678 void pwmd_close(pwm_t *pwm);
 679
 680
 681 /*! \brief Free a previously allocated pointer.
 682  *
 683  * Use this function to free resources allocated by the other libpwmd memory
 684  * functions. Do not use it to free your own allocations.
 685  *
 686  * The difference between the standard free() and this function is that
 687  * this one will zero out the contents of the pointer before freeing it.
 688  *
 689  * \param ptr The pointer to deallocate.
 690  * \return Nothing.
 691  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
 692  * pwmd_process(), pwmd_command()
 693  */
 694 void pwmd_free(void *ptr);
 695
 696
 697 /*! \brief A wrapper around malloc.
 698  *
 699  * Like malloc(), but lets libpwmd keep track of the pointer.
 700  *
 701  * \param size The number of bytes to allocate.
 702  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 703  * \see malloc(3), pwmd_free()
 704  */
 705 void *pwmd_malloc(size_t size)
 706     __attribute__ ((warn_unused_result));
 707
 708
 709 /*! \brief A wrapper around calloc().
 710  *
 711  * Like calloc(), but lets libpwmd keep track of the pointer.
 712  *
 713  * \param nmemb The number of bytes to allocate.
 714  * \param size The number of bytes to allocate.
 715  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 716  * \see calloc(3), pwmd_free()
 717  */
 718 void *pwmd_calloc(size_t nmemb, size_t size)
 719     __attribute__ ((warn_unused_result));
 720
 721
 722 /*! \brief A wrapper around realloc().
 723  *
 724  * Like realloc(), but lets libpwmd keep track of the pointer. Note that this
 725  * function will try and allocate the entire \a size before freeing the
 726  * original pointer and returning the new one.
 727  *
 728  * \param ptr The pointer to reallocate.
 729  * \param size The new number of bytes to allocate.
 730  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 731  * \see realloc(3), pwmd_free()
 732  */
 733 void *pwmd_realloc(void *ptr, size_t size)
 734     __attribute__ ((warn_unused_result));
 735
 736
 737 /*! \brief A wrapper around strdup().
 738  *
 739  * Like strdup(), but lets libpwmd keep track of the pointer.
 740  *
 741  * \param str The string to duplicate.
 742  * \return A newly allocated character pointer or NULL if there wasn't
 743  * enough memory.
 744  * \see strdup(3), pwmd_free()
 745  */
 746 char *pwmd_strdup(const char *str)
 747     __attribute__ ((warn_unused_result));
 748
 749
 750 /*! \def EPWMD_ERROR
 751  *  \hideinitializer
 752  *
 753  * A general pwmd error with no suitable description.
 754  */
 755 #define EPWMD_ERROR             GPG_ERR_USER_1
 756
 757
 758 /*! \def EPWMD_MAX_SLOTS
 759  *  \hideinitializer
 760  *
 761  * The maximum number of cache slots has been reached. There is no available
 762  * slot for a new file.
 763  */
 764 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 765
 766
 767 /*! \def EPWMD_LOOP
 768  *  \hideinitializer
 769  *
 770  * A recursion loop was detected while processing a "target" attribute.
 771  */
 772 #define EPWMD_LOOP              GPG_ERR_USER_3
 773
 774
 775 /*! \def EPWMD_NO_FILE
 776  *  \hideinitializer
 777  *
 778  * A command required an open file, but no file has yet been opened.
 779  */
 780 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 781
 782
 783 /*! \def EPWMD_LIBXML_ERROR
 784  *  \hideinitializer
 785  *
 786  * An XML parse or other libxml2 error occurred.
 787  */
 788 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 789
 790
 791 /*! \def EPWMD_FILE_MODIFIED
 792  *  \hideinitializer
 793  *
 794  * The data file was modified either externally or by another another client
 795  * while trying to process a command.
 796  */
 797 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 798
 799
 800 /*! \def EPWMD_MAX
 801  *  \hideinitializer
 802  * \if cond1
 803  * \endif
 804  */
 805 #define EPWMD_MAX               GPG_ERR_USER_7
 806
 807
 808 /*! \brief Return a description of an error code.
 809  *
 810  * \param code The error code to describe.
 811  * \return A character description of the error code.
 812  * \see pwmd_strerror_r()
 813  */
 814 const char *pwmd_strerror(gpg_error_t code)
 815     __attribute__ ((warn_unused_result));
 816
 817
 818 /*! \brief Return a description of an error code (thread-safe).
 819  *
 820  * This is a thread-safe version of \ref pwmd_strerror().
 821  *
 822  * \param code The error code to describe.
 823  * \param[out] buf An allocated buffer to hold the error description.
 824  * \param size The size of the allocated buffer \a buf.
 825  *
 826  * \retval 0 Success.
 827  * \retval ERANGE \a size was not large enough to hold the entire description
 828  * and \a buf is set to the truncated error string.
 829  */
 830 int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size);
 831
 832 #ifdef __cplusplus
 833 }
 834 #endif
 835
 836 #endif