libmessageclient(3)    FreeBSD Library Functions Manual    libmessageclient(3)

NAME
     libmessageclient – Client Library for libmessage(3)

SYNOPSIS
     #include <messageclient.h>
     -I/usr/local/include -L/usr/local/lib -lmessageclient -lcrypto -lssl

DESCRIPTION
     libmessageclient provides reentrant, blocking-IO code to communicate with
     LibMessage servers.

   USAGE
     The library provides 8 functions.

     char mc_error[ 256 ];

     SSL_CTX *ctx;

     struct mc_ssl {
        SSL *ssl;
        int fd;
     };

     int mc_init_tls( int );
     void mc_deinit_tls();

     struct mc_ssl *mc_connect_to_server( char *, char *, int );
     void mc_close_connection( struct mc_ssl * );

     int mc_read_frame( struct mc_ssl *, unsigned char *, unsigned char );
     int mc_read_message( struct mc_ssl *, unsigned char ** );

     int mc_send_frame( struct mc_ssl *, unsigned char, unsigned int, unsigned char * );
     int mc_send_message( struct mc_ssl *, unsigned int, unsigned char * );

     Do not define any other global symbol beginning with the 3 characters
     ´mc_' because the library reserves that namespace.

   MC_INIT_TLS()
     Use mc_init_tls() to initialize OpenSSL before using any of the other
     functions.  Note that this function sets SIGPIPE to be ignored.

     int mc_init_tls();

     On success, the function returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

   MC_DEINIT_TLS()
     Use mc_deinit_tls() to free the OpenSSL context when you are finished
     using the library.

     void mc_deinit_tls();

   MC_CONNECT_TO_SERVER()
     Use mc_connect_to_server() to establish a connection to a LibMessage
     server.

     struct mc_ssl *mc_connect_to_server( char *hostname, char *port, int ignore );

     The hostname argument is a string representing the hostname or IP address
     of the host on which the server is running.

     The port argument is a string representing the port on which the server
     is listening.

     The ignore argument indicates whether or not to ignore a mismatch between
     the hostname and the hostname on the server's certificate.  This is
     useful for debugging over the loopback interface.

     On success, the function returns a pointer to a struct mc_ssl.

     On failure, the function returns NULL and writes an error message into
     mc_error.

   MC_CLOSE_CONNECTION()
     Use mc_close_tls_connection() to close a connection.

     void mc_close_tls_connection( struct mc_ssl * );

     The function shuts down the TLS connection, closes the underlying
     descriptor, and frees the struct mc_ssl pointed to by the argument.

   MC_READ_FRAME()
     Use mc_read_frame() to read a single frame from a server.  If you want to
     timeout the read, use setsockopt() to place a timeout on the underlying
     socket (the fd member of the struct ssl).

     int mc_read_frame( struct mc_ssl *conn, unsigned char *buffer, unsigned char *final );

     The conn argument is the pointer returned by mc_connect_to_server().

     The buffer argument is a character array of 32767 elements.

     The final argument is a pointer to an unsigned character.

     On success, the function reads an incoming frame's payload into buffer,
     writes the high-order bit of the frame into the high-order bit of final,
     and returns the number of characters read.

     The function returns 0 for an empty frame.

     On error, the function returns -1 and writes an error message into
     mc_error.

     On EOF, the function returns -2.

   MC_READ_MESSAGE()
     Use mc_read_message() to read a complete message from a server.  If you
     want to timeout the read, use setsockopt() to place a timeout on the
     underlying socket (the fd member of the struct ssl).

     int mc_read_message( struct mc_ssl *conn, unsigned char **buffer );

     The conn argument is the pointer returned by mc_connect_to_server().

     The buffer argument is a pointer to a character pointer.

     On success, the function reads an incoming messages's payload into a
     dynamically-allocated buffer that you are responsible for freeing, places
     the a pointer to the buffer in *buffer, and returns the number of
     characters read.

     The function returns 0 for an empty frame.  In that case, *buffer will be
     NULL.

     On error, the function returns -1 and writes an error message into
     mc_error.

     On EOF, the function returns -2.

   MC_SEND_FRAME()
     Use mc_send_frame() to send a frame to a server.

     int mc_send_frame( struct mc_ssl *conn, unsigned int len, unsigned char *buffer );

     The conn argument is the pointer returned by mc_connect_to_server();

     The buffer argument is a character array containing frame data.

     The len argument is the length of the data in buffer.  The length must be
     > 0 and <= 32767.

     On success, the function returns 0.

     If the peer has closed the connection, the function returns -2.

     On other errors, the function returns -1 and writes an error message into
     mc_error.

   MC_SEND_MESSAGE()
     Use mc_send_message() to send a complete message to a server.

     int mc_send_message( struct mc_ssl *conn, unsigned int len, unsigned char *buffer );

     The conn argument is the pointer returned by mc_connect_to_server();

     The buffer argument is a character array containing message data.

     The len argument is the length of the data in buffer.  The length must be
     > 0 and <= 262144.

     On success, the function returns 0.

     If the peer has closed the connection, the function returns -2.

     On other errors, the function returns -1 and writes an error message into
     mc_error.

AUTHORS
     James Bailie ⟨jimmy@mammothcheese.ca⟩
     http://www.mammothcheese.ca

                               Sun Dec 05, 2021