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