/* assuan.h - Definitions for the Assuan IPC library             -*- c -*-
   Copyright (C) 2001-2013 Free Software Foundation, Inc.
   Copyright (C) 2001-2014 g10 Code GmbH

   This file is part of Assuan.

   Assuan is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as
   published by the Free Software Foundation; either version 2.1 of
   the License, or (at your option) any later version.

   Assuan is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with this program; if not, see <http://www.gnu.org/licenses/>.

   @configure_input@
 */

#ifndef ASSUAN_H
#define ASSUAN_H

#include <stdio.h>
@include:sys/types.h@
@include:unistd.h@
#include <stdarg.h>

#ifndef _ASSUAN_NO_SOCKET_WRAPPER
@include:includes@
#endif /*!_ASSUAN_NO_SOCKET_WRAPPER*/

@include:types@

#include <gpg-error.h>

/* Compile time configuration:

   #define _ASSUAN_NO_SOCKET_WRAPPER

   Do not include the definitions for the socket wrapper feature.  */


#ifdef __cplusplus
extern "C"
{
#if 0
}
#endif
#endif

/* The version of this header should match the one of the library.  Do
   not use this symbol in your application; use assuan_check_version
   instead.  */
#define ASSUAN_VERSION @version@

/* The version number of this header.  It may be used to handle minor
   API incompatibilities.  */
#define ASSUAN_VERSION_NUMBER @version-number@


/* Check for compiler features.  */
#if __GNUC__
#define _ASSUAN_GCC_VERSION (__GNUC__ * 10000 \
                            + __GNUC_MINOR__ * 100 \
                            + __GNUC_PATCHLEVEL__)

#if _ASSUAN_GCC_VERSION > 30100
#define _ASSUAN_DEPRECATED  __attribute__ ((__deprecated__))
#endif
#endif
#ifndef _ASSUAN_DEPRECATED
#define _ASSUAN_DEPRECATED
#endif


#define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */

struct assuan_context_s;
typedef struct assuan_context_s *assuan_context_t;
@include:fd-t@

assuan_fd_t assuan_fdopen (int fd);

@include:sock-nonce@


/* Global interface.  */

struct assuan_malloc_hooks
{
  void *(*malloc) (size_t cnt);
  void *(*realloc) (void *ptr, size_t cnt);
  void (*free) (void *ptr);
};
typedef struct assuan_malloc_hooks *assuan_malloc_hooks_t;

/* Categories for log messages.  */
#define ASSUAN_LOG_INIT 1
#define ASSUAN_LOG_CTX 2
#define ASSUAN_LOG_ENGINE 3
#define ASSUAN_LOG_DATA 4
#define ASSUAN_LOG_SYSIO 5
#define ASSUAN_LOG_CONTROL 8

/* If MSG is NULL, return true/false depending on if this category is
   logged.  This is used to probe before expensive log message
   generation (buffer dumps).  */
typedef int (*assuan_log_cb_t) (assuan_context_t ctx, void *hook,
				unsigned int cat, const char *msg);

/* Return or check the version number.  */
const char *assuan_check_version (const char *req_version);

/* Set the default gpg error source.  */
void assuan_set_gpg_err_source (gpg_err_source_t errsource);

/* Get the default gpg error source.  */
gpg_err_source_t assuan_get_gpg_err_source (void);


/* Set the default malloc hooks.  */
void assuan_set_malloc_hooks (assuan_malloc_hooks_t malloc_hooks);

/* Get the default malloc hooks.  */
assuan_malloc_hooks_t assuan_get_malloc_hooks (void);


/* Set the default log callback handler.  */
void assuan_set_log_cb (assuan_log_cb_t log_cb, void *log_cb_data);

/* Get the default log callback handler.  */
void assuan_get_log_cb (assuan_log_cb_t *log_cb, void **log_cb_data);


/* Create a new Assuan context.  The initial parameters are all needed
   in the creation of the context.  */
gpg_error_t assuan_new_ext (assuan_context_t *ctx, gpg_err_source_t errsource,
			    assuan_malloc_hooks_t malloc_hooks,
			    assuan_log_cb_t log_cb, void *log_cb_data);

/* Create a new context with default arguments.  */
gpg_error_t assuan_new (assuan_context_t *ctx);

/* Release all resources associated with the given context.  */
void assuan_release (assuan_context_t ctx);

/* Release the memory at PTR using the allocation handler of the
   context CTX.  This is a convenience function.  */
void assuan_free (assuan_context_t ctx, void *ptr);


/* Set user-data in a context.  */
void assuan_set_pointer (assuan_context_t ctx, void *pointer);

/* Get user-data in a context.  */
void *assuan_get_pointer (assuan_context_t ctx);


/* Definitions of flags for assuan_set_flag().  */
typedef unsigned int assuan_flag_t;

/* When using a pipe server, by default Assuan will wait for the
   forked process to die in assuan_release.  In certain cases this
   is not desirable.  By setting this flag, the waitpid will be
   skipped and the caller is responsible to cleanup a forked
   process. */
#define ASSUAN_NO_WAITPID 1
/* This flag indicates whether Assuan logging is in confidential mode.
   You can use assuan_{begin,end}_condidential to change the mode.  */
#define ASSUAN_CONFIDENTIAL 2
/* This flag suppresses fix up of signal handlers for pipes.  */
#define ASSUAN_NO_FIXSIGNALS 3
/* This flag changes assuan_transact to return comment lines via the
   status callback.  The default is to skip comment lines.  */
#define ASSUAN_CONVEY_COMMENTS 4
/* This flag disables logging for one context.  */
#define ASSUAN_NO_LOGGING 5
/* This flag forces a connection close.  */
#define ASSUAN_FORCE_CLOSE 6

/* For context CTX, set the flag FLAG to VALUE.  Values for flags
   are usually 1 or 0 but certain flags might allow for other values;
   see the description of the type assuan_flag_t for details.  */
void assuan_set_flag (assuan_context_t ctx, assuan_flag_t flag, int value);

/* Return the VALUE of FLAG in context CTX.  */
int assuan_get_flag (assuan_context_t ctx, assuan_flag_t flag);


/* Same as assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 1).  */
void assuan_begin_confidential (assuan_context_t ctx);

/* Same as assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 0).  */
void assuan_end_confidential (assuan_context_t ctx);


/* Direction values for assuan_set_io_monitor.  */
#define ASSUAN_IO_FROM_PEER 0
#define ASSUAN_IO_TO_PEER 1

/* Return flags of I/O monitor.  */
#define ASSUAN_IO_MONITOR_NOLOG 1
#define ASSUAN_IO_MONITOR_IGNORE 2

/* The IO monitor gets to see all I/O on the context, and can return
   ASSUAN_IO_MONITOR_* bits to control actions on it.  */
typedef unsigned int (*assuan_io_monitor_t) (assuan_context_t ctx, void *hook,
					     int inout, const char *line,
					     size_t linelen);

/* Set the IO monitor function.  */
void assuan_set_io_monitor (assuan_context_t ctx,
			    assuan_io_monitor_t io_monitor, void *hook_data);


#define ASSUAN_SYSTEM_HOOKS_VERSION 2
#define ASSUAN_SPAWN_DETACHED 128
struct assuan_system_hooks
{
  /* Always set to ASSUAN_SYTEM_HOOKS_VERSION.  */
  int version;

  /* Sleep for the given number of microseconds.  */
  void (*usleep) (assuan_context_t ctx, unsigned int usec);

  /* Create a pipe with an inheritable end.  */
  int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx);

 /* Close the given file descriptor, created with _assuan_pipe or one
   of the socket functions.  */
  int (*close) (assuan_context_t ctx, assuan_fd_t fd);


  ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer,
		   size_t size);
  ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd,
		    const void *buffer, size_t size);

  int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg,
		  int flags);
  int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd,
		  const assuan_msghdr_t msg, int flags);

  /* If NAME is NULL, don't exec, just fork.  FD_CHILD_LIST is
     modified to reflect the value of the FD in the peer process (on
     Windows).  */
  int (*spawn) (assuan_context_t ctx, pid_t *r_pid, const char *name,
		const char **argv,
		assuan_fd_t fd_in, assuan_fd_t fd_out,
		assuan_fd_t *fd_child_list,
		void (*atfork) (void *opaque, int reserved),
		void *atforkvalue, unsigned int flags);

  /* If action is 0, like waitpid.  If action is 1, just release the PID?  */
  pid_t (*waitpid) (assuan_context_t ctx, pid_t pid,
		    int action, int *status, int options);
  int (*socketpair) (assuan_context_t ctx, int _namespace, int style,
		     int protocol, assuan_fd_t filedes[2]);
  int (*socket) (assuan_context_t ctx, int _namespace, int style, int protocol);
  int (*connect) (assuan_context_t ctx, int sock, struct sockaddr *addr, socklen_t length);
};
typedef struct assuan_system_hooks *assuan_system_hooks_t;


/* Configuration of the default log handler.  */

/* Set the prefix to be used at the start of a line emitted by assuan
   on the log stream.  The default is the empty string.  Note, that
   this function is not thread-safe and should in general be used
   right at startup. */
void assuan_set_assuan_log_prefix (const char *text);

/* Return a prefix to be used at the start of a line emitted by assuan
   on the log stream.  The default implementation returns the empty
   string, i.e. ""  */
const char *assuan_get_assuan_log_prefix (void);

/* Global default log stream.  */
void assuan_set_assuan_log_stream (FILE *fp);

/* Set the per context log stream for the default log handler.  */
void assuan_set_log_stream (assuan_context_t ctx, FILE *fp);


typedef gpg_error_t (*assuan_handler_t) (assuan_context_t, char *);

/*-- assuan-handler.c --*/
gpg_error_t assuan_register_command (assuan_context_t ctx,
				     const char *cmd_string,
				     assuan_handler_t handler,
                                     const char *help_string);
gpg_error_t assuan_register_pre_cmd_notify (assuan_context_t ctx,
					     gpg_error_t (*fnc)(assuan_context_t, const char *cmd));
gpg_error_t assuan_register_post_cmd_notify (assuan_context_t ctx,
					     void (*fnc)(assuan_context_t,
                                                         gpg_error_t));
gpg_error_t assuan_register_bye_notify (assuan_context_t ctx,
					assuan_handler_t handler);
gpg_error_t assuan_register_reset_notify (assuan_context_t ctx,
					  assuan_handler_t handler);
gpg_error_t assuan_register_cancel_notify (assuan_context_t ctx,
					   assuan_handler_t handler);
gpg_error_t assuan_register_input_notify (assuan_context_t ctx,
					  assuan_handler_t handler);
gpg_error_t assuan_register_output_notify (assuan_context_t ctx,
					   assuan_handler_t handler);

gpg_error_t assuan_register_option_handler (assuan_context_t ctx,
					    gpg_error_t (*fnc)(assuan_context_t,
							       const char*,
                                                               const char*));

gpg_error_t assuan_process (assuan_context_t ctx);
gpg_error_t assuan_process_next (assuan_context_t ctx, int *done);
gpg_error_t assuan_process_done (assuan_context_t ctx, gpg_error_t rc);
int assuan_get_active_fds (assuan_context_t ctx, int what,
                           assuan_fd_t *fdarray, int fdarraysize);

const char *assuan_get_command_name (assuan_context_t ctx);

FILE *assuan_get_data_fp (assuan_context_t ctx);
gpg_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line);
gpg_error_t assuan_write_status (assuan_context_t ctx,
				 const char *keyword, const char *text);

/* Negotiate a file descriptor.  If LINE contains "FD=N", returns N
   assuming a local file descriptor.  If LINE contains "FD" reads a
   file descriptor via CTX and stores it in *RDF (the CTX must be
   capable of passing file descriptors).  Under W32 the returned FD is
   a libc-type one.  */
gpg_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line,
                                        assuan_fd_t *rfd);


/*-- assuan-listen.c --*/
gpg_error_t assuan_set_hello_line (assuan_context_t ctx, const char *line);
gpg_error_t assuan_accept (assuan_context_t ctx);
assuan_fd_t assuan_get_input_fd (assuan_context_t ctx);
assuan_fd_t assuan_get_output_fd (assuan_context_t ctx);
gpg_error_t assuan_close_input_fd (assuan_context_t ctx);
gpg_error_t assuan_close_output_fd (assuan_context_t ctx);


/*-- assuan-pipe-server.c --*/
gpg_error_t assuan_init_pipe_server (assuan_context_t ctx,
				     assuan_fd_t filedes[2]);

/*-- assuan-socket-server.c --*/
#define ASSUAN_SOCKET_SERVER_FDPASSING 1
#define ASSUAN_SOCKET_SERVER_ACCEPTED 2
gpg_error_t assuan_init_socket_server (assuan_context_t ctx,
				       assuan_fd_t listen_fd,
				       unsigned int flags);
void assuan_set_sock_nonce (assuan_context_t ctx, assuan_sock_nonce_t *nonce);

/*-- assuan-pipe-connect.c --*/
#define ASSUAN_PIPE_CONNECT_FDPASSING 1
#define ASSUAN_PIPE_CONNECT_DETACHED 128
gpg_error_t assuan_pipe_connect (assuan_context_t ctx,
				 const char *name,
				 const char *argv[],
				 assuan_fd_t *fd_child_list,
				 void (*atfork) (void *, int),
				 void *atforkvalue,
				 unsigned int flags);

/*-- assuan-socket-connect.c --*/
#define ASSUAN_SOCKET_CONNECT_FDPASSING 1
gpg_error_t assuan_socket_connect (assuan_context_t ctx, const char *name,
				   pid_t server_pid, unsigned int flags);

/*-- assuan-socket-connect.c --*/
gpg_error_t assuan_socket_connect_fd (assuan_context_t ctx, int fd,
				   unsigned int flags);

/*-- context.c --*/
pid_t assuan_get_pid (assuan_context_t ctx);
struct _assuan_peercred
{
#ifdef _WIN32
  /* Empty struct not allowed on some compilers.  */
  unsigned int _dummy;
#else
  pid_t pid;
  uid_t uid;
  gid_t gid;
#endif
};
typedef struct _assuan_peercred *assuan_peercred_t;

gpg_error_t assuan_get_peercred (assuan_context_t ctx,
				 assuan_peercred_t *peercred);



/* Client interface.  */
#define ASSUAN_RESPONSE_ERROR 0
#define ASSUAN_RESPONSE_OK 1
#define ASSUAN_RESPONSE_DATA 2
#define ASSUAN_RESPONSE_INQUIRE 3
#define ASSUAN_RESPONSE_STATUS 4
#define ASSUAN_RESPONSE_END 5
#define ASSUAN_RESPONSE_COMMENT 6
typedef int assuan_response_t;

/* This already de-escapes data lines.  */
gpg_error_t assuan_client_read_response (assuan_context_t ctx,
					 char **line, int *linelen);

gpg_error_t assuan_client_parse_response (assuan_context_t ctx,
					  char *line, int linelen,
					  assuan_response_t *response,
					  int *off);

/*-- assuan-client.c --*/
gpg_error_t
assuan_transact (assuan_context_t ctx,
                 const char *command,
                 gpg_error_t (*data_cb)(void *, const void *, size_t),
                 void *data_cb_arg,
                 gpg_error_t (*inquire_cb)(void*, const char *),
                 void *inquire_cb_arg,
                 gpg_error_t (*status_cb)(void*, const char *),
                 void *status_cb_arg);


/*-- assuan-inquire.c --*/
gpg_error_t assuan_inquire (assuan_context_t ctx, const char *keyword,
                               unsigned char **r_buffer, size_t *r_length,
                               size_t maxlen);
gpg_error_t assuan_inquire_ext (assuan_context_t ctx, const char *keyword,
				size_t maxlen,
				gpg_error_t (*cb) (void *cb_data,
						   gpg_error_t rc,
						   unsigned char *buf,
						   size_t buf_len),
				void *cb_data);
/*-- assuan-buffer.c --*/
gpg_error_t assuan_read_line (assuan_context_t ctx,
                              char **line, size_t *linelen);
int assuan_pending_line (assuan_context_t ctx);
gpg_error_t assuan_write_line (assuan_context_t ctx, const char *line);
gpg_error_t assuan_send_data (assuan_context_t ctx,
                              const void *buffer, size_t length);

/* The file descriptor must be pending before assuan_receivefd is
   called.  This means that assuan_sendfd should be called *before* the
   trigger is sent (normally via assuan_write_line ("INPUT FD")).  */
gpg_error_t assuan_sendfd (assuan_context_t ctx, assuan_fd_t fd);
gpg_error_t assuan_receivefd (assuan_context_t ctx, assuan_fd_t *fd);


/*-- assuan-util.c --*/
gpg_error_t assuan_set_error (assuan_context_t ctx, gpg_error_t err,
			      const char *text);



/*-- assuan-socket.c --*/

/* These are socket wrapper functions to support an emulation of Unix
   domain sockets on Windows W32.  */
gpg_error_t assuan_sock_init (void);
void assuan_sock_deinit (void);
int assuan_sock_close (assuan_fd_t fd);
assuan_fd_t assuan_sock_new (int domain, int type, int proto);
int assuan_sock_connect (assuan_fd_t sockfd,
                         struct sockaddr *addr, int addrlen);
int assuan_sock_bind (assuan_fd_t sockfd, struct sockaddr *addr, int addrlen);
int assuan_sock_set_sockaddr_un (const char *fname, struct sockaddr *addr,
                                 int *r_redirected);
int assuan_sock_get_nonce (struct sockaddr *addr, int addrlen,
                           assuan_sock_nonce_t *nonce);
int assuan_sock_check_nonce (assuan_fd_t fd, assuan_sock_nonce_t *nonce);


/* Set the default or per context system callbacks.  This is
   irreversible.  */
void assuan_set_system_hooks (assuan_system_hooks_t system_hooks);

void assuan_ctx_set_system_hooks (assuan_context_t ctx,
				  assuan_system_hooks_t system_hooks);

void __assuan_usleep (assuan_context_t ctx, unsigned int usec);
int __assuan_pipe (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx);
int __assuan_close (assuan_context_t ctx, assuan_fd_t fd);
int __assuan_spawn (assuan_context_t ctx, pid_t *r_pid, const char *name,
		    const char **argv, assuan_fd_t fd_in, assuan_fd_t fd_out,
		    assuan_fd_t *fd_child_list,
		    void (*atfork) (void *opaque, int reserved),
		    void *atforkvalue, unsigned int flags);
int __assuan_socketpair (assuan_context_t ctx, int _namespace, int style,
			 int protocol, assuan_fd_t filedes[2]);
int __assuan_socket (assuan_context_t ctx, int _namespace, int style, int protocol);
int __assuan_connect (assuan_context_t ctx, int sock, struct sockaddr *addr, socklen_t length);
ssize_t __assuan_read (assuan_context_t ctx, assuan_fd_t fd, void *buffer, size_t size);
ssize_t __assuan_write (assuan_context_t ctx, assuan_fd_t fd, const void *buffer, size_t size);
int __assuan_recvmsg (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, int flags);
int __assuan_sendmsg (assuan_context_t ctx, assuan_fd_t fd, const assuan_msghdr_t msg, int flags);
pid_t __assuan_waitpid (assuan_context_t ctx, pid_t pid, int nowait, int *status, int options);


#define ASSUAN_SYSTEM_PTH_IMPL						\
  static void _assuan_pth_usleep (assuan_context_t ctx, unsigned int usec) \
  { (void) ctx; pth_usleep (usec); }					\
  static ssize_t _assuan_pth_read (assuan_context_t ctx, assuan_fd_t fd, \
				void *buffer, size_t size)		\
  { (void) ctx; return pth_read (fd, buffer, size); }			\
  static ssize_t _assuan_pth_write (assuan_context_t ctx, assuan_fd_t fd, \
				 const void *buffer, size_t size)	\
  { (void) ctx; return pth_write (fd, buffer, size); }			\
@include:sys-pth-impl@
  static pid_t _assuan_pth_waitpid (assuan_context_t ctx, pid_t pid,     \
				   int nowait, int *status, int options) \
  { (void) ctx;                                                         \
     if (!nowait) return pth_waitpid (pid, status, options);            \
      else return 0; }							\
									\
  struct assuan_system_hooks _assuan_system_pth =			\
    { ASSUAN_SYSTEM_HOOKS_VERSION, _assuan_pth_usleep, __assuan_pipe,	\
      __assuan_close, _assuan_pth_read, _assuan_pth_write,		\
      _assuan_pth_recvmsg, _assuan_pth_sendmsg,				\
      __assuan_spawn, _assuan_pth_waitpid, __assuan_socketpair,		\
      __assuan_socket, __assuan_connect }

extern struct assuan_system_hooks _assuan_system_pth;
#define ASSUAN_SYSTEM_PTH &_assuan_system_pth

#define ASSUAN_SYSTEM_NPTH_IMPL						\
  static void _assuan_npth_usleep (assuan_context_t ctx, unsigned int usec) \
  { (void) ctx; npth_usleep (usec); }					\
  static ssize_t _assuan_npth_read (assuan_context_t ctx, assuan_fd_t fd, \
				    void *buffer, size_t size)		\
  { ssize_t res; (void) ctx; npth_unprotect();				\
    res = __assuan_read (ctx, fd, buffer, size);			\
    npth_protect(); return res; }					\
  static ssize_t _assuan_npth_write (assuan_context_t ctx, assuan_fd_t fd, \
				     const void *buffer, size_t size)	\
  { ssize_t res; (void) ctx; npth_unprotect();				\
    res = __assuan_write (ctx, fd, buffer, size);			\
    npth_protect(); return res; }					\
  static int _assuan_npth_recvmsg (assuan_context_t ctx, assuan_fd_t fd, \
				  assuan_msghdr_t msg, int flags)	\
  { int res; (void) ctx; npth_unprotect();				\
    res = __assuan_recvmsg (ctx, fd, msg, flags);			\
    npth_protect(); return res; }					\
  static int _assuan_npth_sendmsg (assuan_context_t ctx, assuan_fd_t fd, \
				  const assuan_msghdr_t msg, int flags) \
  { int res; (void) ctx; npth_unprotect();				\
    res = __assuan_sendmsg (ctx, fd, msg, flags);			\
    npth_protect(); return res; }					\
  static pid_t _assuan_npth_waitpid (assuan_context_t ctx, pid_t pid,	\
				     int nowait, int *status, int options) \
  { pid_t res; (void) ctx; npth_unprotect();				\
    res = __assuan_waitpid (ctx, pid, nowait, status, options);		\
    npth_protect(); return res; }					\
									\
  struct assuan_system_hooks _assuan_system_npth =			\
    { ASSUAN_SYSTEM_HOOKS_VERSION, _assuan_npth_usleep, __assuan_pipe,	\
      __assuan_close, _assuan_npth_read, _assuan_npth_write,		\
      _assuan_npth_recvmsg, _assuan_npth_sendmsg,			\
      __assuan_spawn, _assuan_npth_waitpid, __assuan_socketpair,	\
      __assuan_socket, __assuan_connect }

extern struct assuan_system_hooks _assuan_system_npth;
#define ASSUAN_SYSTEM_NPTH &_assuan_system_npth

@include:w32ce-add@

#ifdef __cplusplus
}
#endif
#endif /* ASSUAN_H */
