\input texinfo                      @c -*-texinfo-*-

@c %**start of header

@setfilename assuan.info

@macro copyrightnotice

Copyright @copyright{} 2001--2013 Free Software Foundation, Inc. @*

Copyright @copyright{} 2001--2015 g10 Code GmbH

@end macro

@macro permissionnotice

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU General Public License as published by the

Free Software Foundation; either version 3 of the License, or (at your

option) any later version. The text of the license can be found in the

section entitled ``Copying''.

@end macro

@include version.texi

@settitle Developing with Assuan

@c Create a separate index for command line options.

@defcodeindex op

@c Merge the standard indexes into a single one.

@syncodeindex fn cp

@syncodeindex vr cp

@syncodeindex ky cp

@syncodeindex pg cp

@syncodeindex tp cp

@c A simple macro for optional variables.

@macro ovar{varname}

@r{[}@var{\varname\}@r{]}

@end macro

@c printing stuff taken from gcc.

@macro gnupgtabopt{body}

@code{\body\}

@end macro

@macro gnupgoptlist{body}

@smallexample

\body\

@end smallexample

@end macro

@c Makeinfo handles the above macro OK, TeX needs manual line breaks;

@c they get lost at some point in handling the macro.  But if @macro is

@c used here rather than @alias, it produces double line breaks.

@iftex

@alias gol = *

@end iftex

@ifnottex

@macro gol

@end macro

@end ifnottex

@c Change the font used for @def... commands, since the default

@c proportional one used is bad for names starting __.

@tex

\gdef\mysetfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4}

\global\mysetfont\defbf\ttbshape{10}{\magstep1}

@end tex

@c %**end of header

@ifnottex

@dircategory GNU Libraries

@direntry

* Assuan: (assuan).        An IPC library for non-persistent servers.

@end direntry

This file documents the use and the internals of Assuan.

This is Edition @value{EDITION}, last updated @value{UPDATED}, of

@cite{The `Developing with Assuan' Manual}, for Version @value{VERSION}.

@sp 1

Published by the Free Software Foundation@*

51 Franklin Street, Fifth Floor@*

Boston, MA 02110-1301 USA

@sp 1

@copyrightnotice{}

@sp 1

@permissionnotice{}

@end ifnottex

@setchapternewpage odd

@titlepage

@title Developing with Assuan

@subtitle Version @value{VERSION}

@subtitle @value{UPDATED}

@author by Werner Koch and Marcus Brinkmann

@author @code{@{wk,mb@}@@g10code.com}

@page

@vskip 0pt plus 1filll

@copyrightnotice{}

@sp 2

@permissionnotice{}

@end titlepage

@summarycontents

@contents

@page

@ifnottex

@node Top

@top Introduction

@cindex introduction

This manual documents how to exploit the Assuan library, a simple

interprocess communcation library.

@end ifnottex

@menu

* Introduction::        An introduction to and the motivation behind Assuan.

* Assuan::              Description of the Assuan protocol.

* Implementation::      Overview of the implementation.

* Preparation::         What you should do before using the library.

* Generalities::        Initialization code and data types used.

* Client code::         How to develop an Assuan client.

* Server code::         How to develop an Assuan server.

* External I/O Loop::   How to use external I/O event loops.

* Utilities::           Utility functions.

* Socket wrappers::     Socket wrapper functions.

Miscellaneous

* Library Copying::     GNU Lesser General Public License says

                        how you can copy and share Assuan.

* Copying::             How you can copy and share this manual.

Indices

* Index::	        Index of concepts and symbol names.

@end menu

@c

@c   I N T R O

@c

@node Introduction

@chapter Introduction to Assuan

Assuan is an extensible inter-process communication (IPC) protocol and

library.  It is designed for point-to-point communication and it

doesn't provide a naming system.  To contact a server, either the

client must know how to locate the server, e.g., via a well-known Unix

domain socket, or, if the server is transient, how to start it.  In

the latter case, Assuan provides functionality to start the server

process.

In Assuan, communication is typically either via a pipe or a Unix

domain socket.  This method is neither elegant nor efficient,

especially when there is a lot of data spread across several

transactions.  Not only is there a penalty for an increased number of

context switches, but a significant amount of data is @var{memcpy}ed

from the client to a file descriptor and from the file descriptor to

the server.  Despite these and other disadvantages, this type of

client/server communication is useful: the client is separated from

the server: they run in different address spaces.  This is especially

important in situations where the server must have a known degree of

reliability and data must be protected: as the Assuan protocol is well

defined and clients cannot corrupt the servers' address space,

auditing becomes much easier.

Assuan was developed for use by the GNU Privacy Guard (GnuPG) to

prevent potentially buggy clients from unwittingly corrupting

sensitive transactions or compromising data such as a secret key.

Assuan permits the servers, which do the actual work, e.g., encryption

and decryption of data using a secret key, to be developed

independently of the user interfaces, e.g., mail clients and other

encryption front ends.  Like a shared library, the interface is well

defined and any number of front ends can use it; however, unlike a

shared library, the client cannot see or touch the server's data.  As

with any modular system, Assuan helps keep the components small,

understandable and less error prone.

Assuan is not, however, limited to use with GnuPG servers and clients:

it was designed to be flexible enough to meet the demands of many

transaction-based environments.

@node Assuan

@chapter Description of the Assuan protocol.

The architecture of the modular GnuPG system is based on several

highly specialized modules which form a network of clients and

servers.  A common framework for intermodule communication is

therefore needed and implemented as a library.

Goals:

@itemize @bullet

@item Common framework for module communication

@item Easy debugging

@item Easy module testing

@item Extensible

@item Optional authentication and encryption facility

@item Usable to access external hardware

@end itemize

Design criteria:

@itemize @bullet

@item Client/Server with back channel

@item Use a mainly text based protocol

@item Escape certain control characters

@item Allow indefinite data length

@item Request confidentiality for parts of the communication

@item Dummy module to allow direct linking of client and server

@item Inline data or descriptor passing for bulk data

@item No protection against DoS needed

@item Subliminal channels are not an issue

@end itemize

@node Implementation

@chapter Implementation

The implementation is line based with a maximum line size of 1000

octets.  The default IPC mechanism is Unix Domain Sockets.

On connect, the server responds either with okay or an error status.

To perform an authentication check, the server may send an Inquiry

response prior to the first Okay.  It may also issue Status messages.

The server must check that the client is allowed to connect.  This is

done by requesting the credentials for the peer and comparing them

with the server's credentials.  This avoids attacks based on wrong

socket permissions.

The server may choose to delay the first response in case of an error.

The server, however, never closes the connection, however, the lower

protocol may do so after some time of inactivity or when the

connection enters an error state.

All textual messages are assumed to be in UTF-8 unless otherwise noted.

@menu

* Server responses::    Description of server responses.

* Client requests::     Description of client requests.

* Error codes::         List of error and status codes.

@end menu

@node Server responses

@section Server responses

@table @code

@item OK  [<arbitrary debugging information>]

Request was successful.

@item ERR @var{errorcode} [<human readable error description>]

Request could not be fulfilled.  The possible error codes are defined

by @code{libgpg-error}.

@item S @var{keyword} <status information depending on keyword>

Informational output by the server, which is still processing the

request.  A client may not send such lines to the server while

processing an Inquiry command.  @var{keyword} shall start with a

letter or an underscore.

@item # <string>

Comment line issued only for debugging purposes.  Totally ignored.

@item D <raw data>

Raw data returned to client. There must be exactly one space after the

'D'.  The values for '%', CR and LF must be percent escaped; these are

encoded as %25, %0D and %0A, respectively.  Only uppercase letters

should be used in the hexadecimal representation.  Other characters

may be percent escaped for easier debugging.  All Data lines are

considered one data stream up to the OK or ERR response.  Status and

Inquiry Responses may be mixed with the Data lines.

@item INQUIRE @var{keyword} <parameters>

The server needs further information from the client.  The client

should respond with data (using the ``D'' command and terminated by

``END'').  Alternatively, the client may cancel the current operation

by responding with ``CAN''.

@end table

Consider the following examples (lines prefixed with S indicate text

that the server sends; lines prefixed with C indicate text that the

client sends):

@example

S: INQUIRE foo

C: D foo bar

C: D bar baz

C: END

[Server continues normal work]

@end example

This implements a callback to the client:

@example

S: INQUIRE foo

C: END

[Server continues]

@end example

and:

@example

S: INQUIRE foo

C: CAN

[Server terminates the operaion and in most cases returns an ERR to the client.]

@end example

But, CAN may also mean ``I have no data for you, try to get it from

elsewhere.''

Note: lines longer than 1000 bytes should be treated as a

communication error.  (The rationale for having a line length limit is

to allow for easier multiplexing of several channels.)

@node Client requests

@section Client requests

The server waits for client requests after sending an Okay or Error.

The client should not issue a request in other cases.

@example

@var{command} <parameters>

@end example

@var{command} is a one word string without preceding white space.

Parameters are command specific, CR, LF and the percent signs should

be percent escaped as described above.  To send a backslash as the

last character it should also be percent escaped.  Percent escaping is

allowed anywhere in the parameters but not in the command.  The line

ends with a CR, LF pair or just a LF.

Not yet implemented feature: If there is a need for a parameter list

longer than the line length limit (1000 characters including command

and CR, LF), the last character of the line (right before the CR/LF or

LF) must be a unescaped (i.e., literal) backslash. The following line

is then expected to be a continuation of the line with the backslash

replaced by a blank and the line ending removed.

@example

D <raw data>

@end example

Sends raw data to the server.  There must be exactly one space after

the 'D'.  The values for '%', CR and LF must be percent escaped.

These are encoded as %25, %0D and %0A, respectively.  Only uppercase

letters should be used in the hexadecimal representation.  Other

characters may be percent escaped for easier debugging.  All Data

lines are considered one data stream up to the @code{OK} or @code{ERR}

response.  Status and Inquiry Responses may be mixed with the Data

lines.

@example

END

@end example

Lines beginning with a @code{#} or empty lines are ignored.  This is

useful to comment test scripts.

Although the commands are application specific, some of them are used

by all protocols and partly supported by the Assuan library:

@table @code

@item BYE

Close the connection.  The server will respond with @code{OK}.

@item RESET

Reset the connection but not any existing authentication.  The server

should release all resources associated with the connection.

@item END

Used by a client to mark the end of raw data.  The server may send

@code{END} to indicate a partial end of data.

@item HELP

Lists all commands that the server understands as comment lines on the

status channel.

@item QUIT

Reserved for future extensions.

@item OPTION

Set options for the connection.  The syntax of such a line is

@display

  OPTION @var{name} [ [=] @var{value} ]

@end display

Leading and trailing spaces around @var{name} and @var{value} are

allowed but should be ignored.  For compatibility reasons, @var{name}

may be prefixed with two dashes.  The use of the equal sign is optional

but suggested if @var{value} is given.

@item CANCEL

This command is reserved for future extensions.

@item AUTH

This command is reserved for future extensions.  Not yet specified as

we don't implement it in the first phase.  See Werner's mail to gpa-dev on

2001-10-25 about the rationale for measurements against local attacks.

@item NOP

No operation.  Returns OK without any action.

@end table

@node Error codes

@section Error codes

Libassuan is used with gpg-error style error codes.  It is recommended

to set the error source to a different value from the default

@code{GPG_ERR_SOURCE_UNKNOWN} by calling @ref{function

assuan_set_gpg_err_source} early.

@c

@c           P R E P A R A T I O N

@c

@node Preparation

@chapter Preparation

To use @sc{Assuan}, you have to make some changes to your

sources and the build system.  The necessary changes are small and

explained in the following sections.

@menu

* Header::                 What header file you need to include.

* Building sources::       How to build sources using the library.

* Automake::               How to build sources with the help of Automake.

* Multi Threading::        How @code{libassuan} can be used in a MT environment.

@end menu

@node Header

@section Header

All interfaces (data types and functions) of @code{libassuan} are defined

in the header file @file{assuan.h}.  You must include this in all source

files using the library, either directly or through some other header

file, like this:

@example

#include <assuan.h>

@end example

The namespace of @code{libassuan} is @code{assuan_*} for function

and type names and @code{ASSUAN*} for other symbols.  In addition the

same name prefixes with one prepended underscore are reserved for

internal use and should never be used by an application.

Because @code{libassuan} makes use of the GPG Error library, using

@code{libassuan} will also use the @code{GPG_ERR_*} namespace

directly, and the @code{gpg_err*} and @code{gpg_str*} namespaces

indirectly.

@node Building sources

@section Building sources

If you want to compile a source file including the @file{assuan.h}

header file, you must make sure that the compiler can find it in the

directory hierarchy.  This is accomplished by adding the path to the

directory in which the header file is located to the compilers include

file search path (via the @option{-I} option).

However, the path to the include file is determined at the time the

source is configured.  To solve this problem, @code{libassuan} ships with

a small helper program @command{libassuan-config} that knows the path to

the include file and other configuration options.  The options that need

to be added to the compiler invocation at compile time are output by the

@option{--cflags} option to @command{libassuan-config}.  The following

example shows how it can be used at the command line:

@example

gcc -c foo.c $(libassuan-config --cflags)

@end example

Adding the output of @samp{libassuan-config --cflags} to the compiler's

command line will ensure that the compiler can find the @file{assuan.h}

header file.

A similar problem occurs when linking the program with the library.

Again, the compiler/linker has to find the library files.  For this to

work, the path to the library files has to be added to the library

search path (via the @option{-L} option).  For this, the option

@option{--libs} to @command{libassuan-config} can be used.  For

convenience, this option also outputs all other options that are

required to link the program with the @code{libassuan} libraries (in

particular, the @option{-lassuan} option).  The example shows how to

link @file{foo.o} with the @code{libassuan} library to a program

@command{foo}.

@example

gcc -o foo foo.o $(libassuan-config --libs)

@end example

You can also combine both examples to a single command by specifying

both options to @command{libassuan-config}:

@example

gcc -o foo foo.c $(libassuan-config --cflags --libs)

@end example

@node Automake

@section Building sources using Automake

It is much easier if you use GNU Automake instead of writing your own

Makefiles.  If you do that you do not have to worry about finding and

invoking the @command{libassuan-config} script at all.  @code{libassuan}

provides an Automake macro that does all the work for you.

@defmac AM_PATH_LIBASSUAN (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})

Check whether @code{libassuan} (at least version

@var{minimum-version}, if given) exists on the host system.  If it is

found, execute @var{action-if-found}, otherwise do

@var{action-if-not-found}, if given.

Additionally, the function defines @code{LIBASSUAN_CFLAGS} to the

flags needed for compilation of the program to find the

@file{assuan.h} header file, and @code{LIBASSUAN_LIBS} to the linker

flags needed to link the program to the @code{libassuan} library.

@end defmac

You can use the defined Autoconf variables like this in your

@file{Makefile.am}:

@example

AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)

LDADD = $(LIBASSUAN_LIBS)

@end example

@node Multi Threading

@section Multi Threading

The @code{libassuan} library is designed so that it can be used in a

threaded application, if some rules are followed.

@itemize @bullet

@item Run the initialization functions before you actually start

to use threads.  Specifically, the functions

@code{assuan_set_gpg_err_source}, @code{assuan_set_malloc_hooks} and

@code{assuan_set_log_cb} should not be called concurrently with

@code{assuan_new}.  Use @code{assuan_new_ext} instead or ensure proper

serialization.

@item Only one thread at a time may access an @code{libassuan} context.

@item If you use the default log handler, use

@code{assuan_set_assuan_log_stream} to setup a default log stream.

@item If you have callback functions shared by multiple functions,

the callback function must be reentrant for that purpose.

@code{libassuan} does not serialize invocation of callback functions

across contexts.

@end itemize

@c

@c     G E N E R A L I T I E S

@c

@node Generalities

@chapter Generalities

@menu

* Data Types:: Data types used by @code{libassuan}.

* Initializing the library:: How to initialize the library.

* Default Log Handler:: How to configure the default log handler.

* Contexts:: How to work with contexts.

* Reading and Writing:: How to communicate with the peer.

@end menu

@node Data Types

@section Data Types used by the library

@sc{Assuan} uses a so-called context to store a connection's state.

The following data type is used for that:

@deftp {Data type} assuan_context_t

The @code{assuan_context_t} type is a pointer to an object maintained

internally by the library.  Contexts are allocated with

@code{assuan_new} or @code{assuan_new_ext} and released with

@code{assuan_release}.  Other functions take this data type to access

the state created by these functions.

@end deftp

@deftp {Data type} assuan_fd_t

The @code{assuan_fd_t} is a file descriptor (in Unix) or a system

handle (in Windows).  The special value @code{ASSUAN_INVALID_FD} is

used to specify invalid Assuan file descriptors.

@end deftp

@deftypefun assuan_fd_t assuan_fdopen (@w{int @var{fd}})

Create an assuan file descriptor from a POSIX (libc) file descriptor

@var{fd}.  On Unix, this is equivalent to @code{dup}, while on Windows

this will retrieve the underlying system handle with

@code{_get_osfhandle} and duplicate that.

@end deftypefun

@node Initializing the library

@section Initializing the library

Libassuan makes use of Libgpg-error and assumes that Libgpg-error has

been initialized.  In general @code{gpgrt_check_version} should be

called to guarantee this; the Libgpg-error manual for details.

Libassuan itself requires no initialization. There are however some

initialization hooks provided which are often useful.  These should be

called as early as possible and in a multi-threaded application before

a second thread is created.

These functions initialize default values that are used at context

creation with @code{assuan_new}.  As there can only be one default,

all values can also be set directly with @code{assuan_new_ext} or with

context-specific functions after context creation.

If your application uses its own memory allocation functions or wrappers

it is good idea to tell @code{libassuan} about it so it can make use of the

same functions or wrappers:

@deftp {Data type} {struct assuan_malloc_hooks}

This structure is used to store the memory allocation callback

interface functions.  It has the following members, whose semantics

are identical to the corresponding system functions:

@table @code

@item void *(*malloc) (size_t cnt)

This is the function called by @sc{Assuan} to allocate memory for a context.

@item void *(*realloc) (void *ptr, size_t cnt)

This is the function called by @sc{Assuan} to reallocate memory for a context.

@item void (*free) (void *ptr)

This is the function called by @sc{Assuan} to release memory for a context.

@end table

@end deftp

@deftp {Data type} {assuan_malloc_hooks_t}

This is a pointer to a @code{struct assuan_malloc_hooks}.

@end deftp

@deftypefun void assuan_set_malloc_hooks (@w{assuan_malloc_hooks_t @var{malloc_hooks}})

This function sets the default allocation hooks for new contexts

allocated with @code{assuan_new}.  You need to provide all three

functions.  Those functions need to behave exactly as their standard

counterparts @code{malloc}, @code{realloc} and @code{free}.  If you

write your own functions, please take care to set @code{errno}

whenever an error has occurred.

@end deftypefun

@deftypefun assuan_malloc_hooks_t assuan_get_malloc_hooks ()

This function gets the default allocation hooks for new contexts

allocated with @code{assuan_new}.  The result structure is statically

allocated and should not be modified.

@end deftypefun

The @sc{Assuan} library uses @code{libgpg-error} error values, which

consist and error code and an error source.  The default source used

by contexts allocated with @code{assuan_new} can be set with the

following function.

@anchor{function assuan_set_gpg_err_source}

@deftypefun void assuan_set_gpg_err_source (@w{gpg_err_source_t @var{err_source}})

This function sets the default error source for errors generated by

contexts allocated with @code{assuan_new}.

One way to call this function is

@smallexample

assuan_set_gpg_err_source (GPG_ERR_SOURCE_DEFAULT);

@end smallexample

@end deftypefun

@deftypefun gpg_err_source_t assuan_get_gpg_err_source (void)

This function gets the default error source for errors generated by

contexts allocated with @code{assuan_new}.

@end deftypefun

@noindent

To integrate assuan logging and diagnostics into your own logging

system, you may use the following two functions:

@deftp {Data type} {int (*assuan_log_cb_t) (@w{assuan_context_t @var{ctx}}, @w{void *@var{hook_value}}, @w{unsigned int @var{cat}}, @w{const char *@var{msg}})}

The user-provided callback function takes a context @var{ctx}, for

which the message @var{msg} was generated, and a hook value

@var{hook_value} that was supplied when the log handler was registered

for the context with @code{assuan_set_log_cb}, and a category

@var{cat}.  The category is one of:

@table @code

@item ASSUAN_LOG_INIT

@item ASSUAN_LOG_CTX

@item ASSUAN_LOG_ENGINE

@item ASSUAN_LOG_DATA

RFU

@item ASSUAN_LOG_SYSIO

Log lowlevel I/O data.

@item ASSUAN_LOG_CONTROL

Log the control channel.

@end table

The user may then, depending on the category, write the message to a

log file or treat it in some other way.

If @var{msg} is a null pointer, then no message should be logged, but

the function should return 1 if it is interested in log messages with

the category @var{cat}.  If it is not interested, 0 should be

returned.  This allows @code{libassuan} to suppress the generation of

expensive debug output.

@end deftp

@deftypefun void assuan_set_log_cb (@w{assuan_log_cb_t @var{log_cb}}, @w{void *@var{log_cb_data}})

This function sets the default logging handler for log messages

generated by contexts allocated with @code{assuan_new}.

@end deftypefun

@deftypefun void assuan_get_log_cb (@w{assuan_log_cb_t *@var{log_cb}}, @w{void **@var{log_cb_data}})

This function gets the default logging handler for log messages

generated by contexts allocated with @code{assuan_new}.

@end deftypefun

You do not need to set a log handler, as @sc{Assuan} provides a

configurable default log handler that should be suitable for most

purposes.  Logging can be disabled completely by setting the log

handler to a null pointer.

@node Default Log Handler

@section Default Log Handler

The default log handler can be configured by the following functions:

@deftypefun void assuan_set_assuan_log_prefix (@w{const char *@var{text}})

Set the prefix to be used at the start of a line emitted by assuan

on the log stream to @var{text}.  The default is the empty string.

@end deftypefun

@deftypefun @w{const char *} assuan_get_assuan_log_prefix (void)

Return the prefix to be used at the start of a line emitted by assuan

on the log stream.  The default implementation returns the empty

string.

@end deftypefun

@deftypefun void assuan_set_assuan_log_stream (FILE *@var{fp})

This sets the default log stream to which @code{libassuan} should log messages not

associated with a specific context to @var{fp}.  The default is to log

to @code{stderr}.  This default value is also changed by using

@code{assuan_set_log_stream} (to set a logging stream for a specific

context) unless this function has been used.  Obviously this is not

thread-safe and thus it is highly recommended to use this function to

setup a proper default.

@end deftypefun

@deftypefun @w{FILE *} assuan_get_assuan_log_stream (void)

Return the stream which is currently being using for global logging.

@end deftypefun

The log stream used by the default log handler can also be set on a

per context basis.

@deftypefun void assuan_set_log_stream (@w{assuan_context_t @var{ctx}}, @w{FILE *@var{fp}})

Enable debugging for the context @var{ctx} and write all debugging

output to the stdio stream @var{fp}.  If the default log stream (used

for non-context specific events) has not yet been set, a call to this

functions implicitly sets this stream also to @var{fp}.

@end deftypefun

@node Contexts

@section How to work with contexts

Some operations work globally on the library, but most operate in a

context, which saves state across operations.  To allow the use of

@code{libassuan} in mixed environments, such as in a library using

GPGME and an application using GPGME, the context is very extensive

and covers utilitary information like memory allocation callbacks as

well as specific information associated with client/server operations.

@anchor{function assuan_new}

@deftypefun gpg_error_t assuan_new (@w{assuan_context_t *@var{ctx_p}})

The function @code{assuan_new} creates a new context, using the global

default memory allocation, log handler and @code{libgpg-error} source.

It is equivalent to

@smallexample

gpg_error_t err;

assuan_log_cb_t log_cb;

void *log_cb_data;

assuan_get_log_cb (&log_cb, &log_cb_data);

err = assuan_new_ext (ctx_p, assuan_get_gpg_err_source (),

                      assuan_get_malloc_hooks (), log_cb, log_cb_data);

@end smallexample

As you can see, this is not thread-safe.  Take care not to modify the

memory allocation hooks or log callback handler concurrently with

@code{assuan_new}.

The function returns an error if a memory allocation error occurs, and

0 with the new context in @var{ctx_p} otherwise.

@end deftypefun

@deftypefun gpg_error_t assuan_new_ext (@w{assuan_context_t *@var{ctx_p}}, @w{gpg_err_source_t @var{err_source}}, @w{assuan_malloc_hooks_t @var{malloc_hooks}}, @w{assuan_log_cb_t @var{log_cb}}, @w{void *@var{log_cb_data}})

The function @code{assuan_new_ext} creates a new context using the

supplied @code{libgpg-error} error source @var{err_source}, the memory

allocation hooks @var{malloc_hooks} and the log handler @var{log_cb}

with the user data @var{log_cb_data}.

@end deftypefun

After the context has been used, it can be destroyed again.

@deftypefun void assuan_release (assuan_context_t ctx)

The function @code{assuan_release} destroys the context CTX and

releases all associated resources.

@end deftypefun

Other properties of the context beside the memory allocation handler,

the log handler, and the @code{libgpg-error} source can be set after

context creation.  Here are some of them:

@deftypefun void assuan_set_pointer (@w{assuan_context_t @var{ctx}}, @w{void *@var{pointer}})

Store the arbitrary pointer value @var{pointer} into the context

@var{ctx}.  This is useful to provide command handlers with additional

application context.

@end deftypefun

@deftypefun void* assuan_get_pointer (@w{assuan_context_t @var{ctx}})

This returns the pointer for context @var{ctx} which has been set using

the above function.  A common way to use it is by setting the pointer

before starting the processing loop and to retrieve it right at the

start of a command handler:

@smallexample

static int

cmd_foo (assuan_context_t ctx, char *line)

@{

  ctrl_t ctrl = assuan_get_pointer (ctx);

  ...

@}

@end smallexample

@end deftypefun

@deftypefun void assuan_set_flag (@w{assuan_context_t @var{ctx}}, @w{assuan_flag_t @var{flag}}, @w{int @var{value}})

Set the the @var{flag} for context @var{ctx} to @var{value}.  Values for

flags are usually 1 or 0 but certain flags might need other values.

@deftp {Data type} assuan_flag_t

The flags are all named and collected in an @code{enum} for better readability.

Available flags are:

@table @code

@item ASSUAN_NO_WAITPID

When using a pipe server, by default Libassuan will wait for the forked

process to die in @code{assuan_release}.  In certain cases this is

not desirable.  By setting this flag, a call to @code{waitpid} will be

suppressed and the caller is responsible to cleanup the child process.

@item ASSUAN_CONFIDENTIAL

Use to return the state of the confidential logging mode.

@item ASSUAN_NO_FIXSIGNALS

Do not modify signal handler for @code{SIGPIPE}.

@item ASSUAN_CONVEY_COMMENTS

If enabled comment lines are passed to the status callback of the

@code{assuan_transact}.

@item ASSUAN_FORCE_CLOSE

Setting this flag forces the next command to assume that the

connection has been closed.  This breaks the command processing loop

and may be used as an implicit BYE command.  @var{value} is ignored

and thus it is not possible to clear this flag.

@end table

@end deftp

@end deftypefun

@deftypefun int assuan_get_flag (@w{assuan_context_t @var{ctx}}, @w{assuan_flag_t @var{flag}})