/* assuan.h - Definitions for the Assuan IPC library             -*- c -*-
 * Copyright (C) 2001-2013 Free Software Foundation, Inc.
 * Copyright (C) 2001-2021 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/>.
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * @configure_input@
 */

/* Compile time configuration:
 *
 * #define _ASSUAN_NO_SOCKET_WRAPPER
 *
 * Do not include the definitions for the socket wrapper feature.
 */

#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>

#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);

/* Codes used with the gcry_control function. */
enum assuan_ctl_cmds
  {
    ASSUAN_CONTROL_NOP = 0,
    ASSUAN_CONTROL_REINIT_SYSCALL_CLAMP = 1
  };

/* Perform control operations defined by CMD.  */
gpg_error_t assuan_control (enum assuan_ctl_cmds cmd, void *arg);


/* 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);

/*
 * 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);


/* The type for assuan command handlers.  */
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 Windows 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, assuan_fd_t 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, so, put this (not valid).  */
  pid_t pid;
#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.
 */

/* Client response codes.  */
#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 --*/

/* This flag is used with assuan_sock_connect_byname to
 * connect via SOCKS.  */
#define ASSUAN_SOCK_SOCKS   1

/* This flag is used with assuan_sock_connect_byname to force a
   connection via Tor even if the socket subsystem has not been
   swicthed into Tor mode.  This flags overrides ASSUAN_SOCK_SOCKS. */
#define ASSUAN_SOCK_TOR     2

/* These are socket wrapper functions to support an emulation of Unix
 * domain sockets on Windows.  */
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_set_flag (assuan_fd_t sockfd, const char *name, int value);
int assuan_sock_get_flag (assuan_fd_t sockfd, const char *name, int *r_value);
assuan_fd_t assuan_sock_accept (assuan_fd_t sockfd,
                                struct sockaddr *addr, socklen_t *p_addrlen);
int assuan_sock_connect (assuan_fd_t sockfd,
                         struct sockaddr *addr, int addrlen);
assuan_fd_t assuan_sock_connect_byname (const char *host, unsigned short port,
                                        int timeout,
                                        const char *credentials,
                                        unsigned int flags);
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);

gpg_error_t assuan_pipe_wait_server_termination (assuan_context_t ctx,
                                                 int *status, int no_hang);

gpg_error_t assuan_pipe_kill_server (assuan_context_t ctx);

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