.TH IMCLIENT 3 "Project Cyrus" CMU
.\"
.\" Copyright (c) 1994-2008 Carnegie Mellon University.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. The name "Carnegie Mellon University" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For permission or any legal
.\"    details, please contact
.\"      Carnegie Mellon University
.\"      Center for Technology Transfer and Enterprise Creation
.\"      4615 Forbes Avenue
.\"      Suite 302
.\"      Pittsburgh, PA  15213
.\"      (412) 268-7393, fax: (412) 268-7395
.\"      innovation@andrew.cmu.edu
 *
.\" 4. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by Computing Services
.\"     at Carnegie Mellon University (http://www.cmu.edu/computing/)."
.\"
.\" CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
.\" THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
.\" FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
.\" AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" $Id: imclient.3,v 1.14 2010/01/06 17:01:51 murch Exp $
.SH NAME
imclient \- (library) authenticating callback interface to IMAP/IMSP servers
.SH SYNOPSIS
.ad l
.ft B
#include <cyrus/imclient.h>
.sp
.ft
.if
.LP
.ft B 
.BI "int imclient_connect(struct imclient **" imclient ", const char *" host ", const char *" port ");" 
.PP
.BI "void imclient_close (struct imclient *" imclient ");"
.sp .025i
.BI "void imclient_setflags(struct imclient *" imclient ", int" flags ");"
.sp .025i
.BI "void imclient_clearflags (struct imclient *" imclient ", int" flags ");"
.sp .025i
.BI "char* imclient_servername (struct imclient *" imclient ");"
.sp .025i
.B "void imclient_addcallback (struct imclient *" imclient ",...);"
.sp .025i
.BI "void imclient_send (struct imclient *" imclient ", void (*" finishproc ")(), void *" finishrock ", const char *" fmt ", ...);"
.sp .025i
.BI "void imclient_getselectinfo (struct imclient *" imclient ", int *" fd ", int * " wanttowrite ");"
.sp .025i
.BI "void imclient_processoneevent (struct imclient *" imclient ");"
.sp .025i
.BI "int imclient_authenticate (struct imclient *" imclient ", struct sasl_client **" availmech ", const char *" service ", const char *" user ", int " protallowed ");"
.sp .025i
.BI "int imclient_havetls ();"
.sp .025i
.BI "int imclient_starttls (struct imclient *" imclient ", char *" cert_file ", char *" key_file ", char *" CAfile ", char *" CApath ");"

.SH DESCRIPTION
The imclient library functions are distributed with Cyrus IMAP and IMSP.
These functions are used for building IMAP/IMSP client software. These
functions handle Kerberos authentication and can set callbacks based on the
keyword in untagged replies or based on the command tag at the end of
command replies.

Users must link with the -lcyrus switch, and must supply a function called
.I fatal
to be called in case of any error within
.I libcyrus.a.
.PP
All of the
.B imclient
functions begin with the prefix 
.I imclient
and takes  an  argument of type
.B struct imclient *
as the first argument which is  initialized by
.B imclient_connect
and freed by
.B imclient_close.

See below for a description of each function.

.IP \fB\imclient_connect() \fP5
Connects the client server to the host. If successful, it returns 0
and sets the imclient argument to a pointer to an 
.B imclient 
struct. The 
.B imclient 
struct represents the current connection,  flags, and  callbacks. On failure, the current
.B errno
is returned if a system call failed,  -1 is returned if the host name was not found, and  -2 is returned if the service name was not found. 
.IP \fB\imclient_close() \fP5
Closes and frees the 
.B imclient 
connection. 
.IP \fB\ imclient_setflags() \fP5
Sets the flags specified by the
.B flags
argument on the
.B imclient
connection. Currently the only  flag allowed is
.B IMCLIENT_CONN_NONSYNCLITERAL
(this flag indicates that the server supports non-synchronizing literals described by the LITERAL+ extension).
.IP \fB\imclient_clearflags() \fP5
Clears the flags specified by the
.B flags
argument on the 
.B imclient
connection.
.IP \fB\imclient_servername() \fP5
Returns a  char * pointer to the name of the server connected to by
.B imclient.
.IP \fB\imclient_addcallback() \fP5
Adds an untagged data callback to the 
.B imclient
connection. The function
.B imclient_addcallback
takes callbacks of the type
.B imclient_proc_t
which is defined to be:
.in 1.5i
typedef void imclient_proc_t (struct imclient *imclient, void *rock, struct imclient_reply *reply);
.in
.sp .025i
and
.B struct imclient_reply *
is defined to be:
.sp .025i
.in 1.5i
struct imclient_reply {
.in
.in 2i
    char *keyword;
    long msgno;
    char *text;
.in
.in 1.5i
};
.in
.sp
After the first argument
.B imclient,
there can be zero or more instances of the set of 
.B keyword,
.B flags,
.B proc,
and
.B rock,
each adding or changing a single callback.
Each instance  adds or changes the callback for
.B keyword. 
The argument,
.B flags,
specifies information about the parsing of the untagged data.
.B proc
and
.B rock
specify the callback function and rock to invoke when the untagged
data is received.
.B proc
may be a null pointer, in which case no function
is invoked.  The callback function may not call the functions
.B imclient_close(), imclient_send(), imclient_eof(),
.B imclient_processoneevent(),
or
.B imclient_authenticate()
on the
connection. The callback function may over write  the text of untagged
data.
.IP \fB\imclient_send() \fP5
Sends a new command to the 
.B imclient
connection.
.B finishproc
and 
.B finnishrock
are the function and rock called when the  command completes. 
.B functionproc
may be a null pointer, in which case no callback is made. The call back function may not call the functions
.B imclient_close(), imclient_send(), imclient_eof(),  imclient_processoneevent(), 
or 
.B imclient_authenticate() 
on the connection.
The argument,
.B fmt
, is a print like specification of the command. It must not include the 
tag as the tag is automatically added by imclient_send().
The defined %-sequences are:
.sp .025i
.in 1.5i
.B %%
for %
.sp .025i
.B %a
for an IMAP atom
.sp .025i
.B %s
for an astring (which will be quoted or literalized as needed)
.sp .025i
.B %d
for a decimal
.sp .025i
.B %u
for an unsigned  decimal
.sp .025i
.B %v
for #astring (argument is a null-terminated array of
.B char *
which are written as space separated astrings)
.in
.IP \fB\imclient_getselectinfo() \fP5
Gets the information for calling
.B select(2).
.B fd
is filled in with the file
descriptor to
.B select(2)
for read.
.B wanttowrite
is filled in with a
nonzero value if select should be used for write as well. 
.IP \fB\imclient_processoneevent() \fP5
Processes one input or output event on the
.B imclient
connection.
.IP \fB\imclient_authenticate() \fP5
Authenticates the 
.B imclient 
connection using one of the mechanisms in
.B availmech.
The argument,
.B user,
if not NULL, specifies the user to
authenticate as. If the user is NULL, the current user is used.  The
argument
.B protallowed
is a bitmask of permissible protection mechanisms.
.sp .025i
On success, 0 is returned.  On failure (i.e., "BAD" keyboard, or no
authentication mechanisms worked), 1 is returned. On extreme failure
(premature "OK"), 2 is returned.
.IP \fB\imclient_havetls() \fP5
Returns a Boolean indicating whether the
.B imclient
library was compiled with TLS (SSL) support.  If so,
.B imclient_starttls()
may be used to secure the IMAP connection.
.IP \fB\imclient_starttls() \fP5
Issues a STARTTLS command on an existing IMAP connection and
negotiates the secure link.  The
.B cert_file
and
.B key_file
arguments specify the client certificate and secret key to use to
authenticate ourselves to the server.  If client authentication is not
needed, set both of these arguments to NULL.
.sp
The
.B CAfile
and
.B CApath
arguments specify a file or directory, respectively, of CA
certificates for validating server certificates.  (See
.B SSL_CTX_load_verify_locations(3)
for details.)  If both of these are NULL, the client will be unable to
validate the server's certificate, in which case the connection may
succeed but a warning will be printed to stdout.

.SH EXAMPLES
The following code is a possible skeletion of
.B imclient
that relies on Kerberos to do authentication.  This code preforms an IMAP
CAPABILITY request and prints out the result.
.nf

struct sasl_client;
#include <cyrus/xmalloc.h> /* example uses xstrdup */
#include <cyrus/sasl.h>
#include <cyrus/imclient.h>
#include <stdio.h>

extern struct sasl_client krb_sasl_client;

struct sasl_client *login_sasl_client[] = {
    &krb_sasl_client, 
    NULL
};
struct imclient *imclient;
char server[] = "cyrus.andrew.cmu.edu" ;
char port[] = "imap";

void fatal(char* message, int rc) {
    fprintf(stderr, "fatal error: %s\en", message);
    exit(rc);
}

static void callback_capability(struct imclient *imclient,
				void *rock,
				struct imclient_reply *reply) {
    if (reply->text != NULL) {
	*((char**)rock) = xstrdup( reply->text );
    }
}

static void end_command (struct imclient *connection, void*
			rock,  struct imclient_reply *inmsg) {
    (*(int*)rock)--;
}

main() {
    char* capability_string;
    int nc;
    
    if (imclient_connect(&imclient, server, port)) {
	fprintf(stderr,
		"error: Couldn't connect to %s %s\en",
		server, port);
	exit(1);
    }

    if (imclient_authenticate(imclient, login_sasl_client, "imap"
			      /* service */,
			      NULL /* user */, SASL_PROT_ANY)) {
	exit(1);
    }

    imclient_addcallback(imclient, "CAPABILITY",
			 CALLBACK_NOLITERAL,
			 callback_capability,
			 &capability_string,
			 NULL);
    
    nc = 1;
    
    imclient_send(imclient, end_command,
		  (void*) &nc, "CAPABILITY");
    
    while(nc > 0) {
	imclient_processoneevent(imclient);
    }
    
    if (strstr("LITERAL+", capability_string)) {
	imclient_setflags(imclient, IMCLIENT_CONN_NONSYNCLITERAL);
    }

    imclient_send(imclient, NULL, NULL, "LOGOUT");
    imclient_close(imclient);

    printf("capability text is: %s\en", capability_string);

    free(capability_string);
}
.fi

.SH BUGS
No known bugs.

.SH SEE ALSO
.B cyradm, imapd, imspd,
RFC2033 (IMAP LITERAL+ extension), RFC2060 (IMAP4rev1 specification), and
.B select(2)

.SH KEYWORDS
IMAP, ACAP, IMSP, Kerberos, Authentication