New audio subsystem.

[jog] / txport.h

/* -*-c-*-
 *
 * $Id: txport.h,v 1.2 2002/01/30 09:27:10 mdw Exp $
 *
 * Transport switch glue
 *
 * (c) 2001 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Jog: Programming for a jogging machine.
 *
 * Jog is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * Jog 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 General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with Jog; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: txport.h,v $
 * Revision 1.2  2002/01/30 09:27:10  mdw
 * Transport configuration overhaul.  Configuration string is now a list of
 * `;'-separated `key=value' strings, which can be handled either by the
 * core or the transport module.  The newline character(s) are a core
 * parameter now.
 *
 * Revision 1.1  2002/01/25 19:34:45  mdw
 * Initial revision
 *
 */

#ifndef TXPORTSW_H
#define TXPORTSW_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifdef HAVE_CONFIG_H
#  include "config.h"
#endif

#include <stdarg.h>
#include <stddef.h>

#include <pthread.h>

#include <mLib/darray.h>
#include <mLib/lbuf.h>

/*----- Data structures ---------------------------------------------------*/

/* --- Vector of bytes --- */

#ifndef UCHAR_V
#  define UCHAR_V
   DA_DECL(uchar_v, unsigned char);
#endif

/* --- Node for lines --- */

typedef struct txline {
  struct txline *next, *prev;		/* Next node in the list */
  struct txport *tx;			/* Owning transport */
  char *s;				/* Pointer to the text */
  size_t len;				/* Length of the string */
} txline;

/* --- A transport context --- *
 *
 * The only members for which there is contention are the state @s@ and the
 * raw incoming buffer @buf@.  Other members may be accessed without locking
 * the structure.  Thus, the thread messing about is essentially isolated to
 * the data- fetching thread and the line buffering code.
 */

typedef struct txport {
  struct txport_ops *ops;		/* Operations table */
  pthread_t tid;			/* Fetching thread id */
  pthread_mutex_t mx;			/* Lock for this structure */
  pthread_cond_t cv;			/* `New data has arrived' */
  unsigned s;				/* State of this transport */
  uchar_v buf;				/* Buffer of incoming data */
  lbuf lb;				/* Buffer for extracting lines */
  txline *ll, *ll_tail;			/* List of waiting lines, in order */
} txport;

enum {
  TX_READY,				/* More data may arrive */
  TX_CLOSE,				/* No more data will arrive */
  TX_CLOSED				/* Done the closure thing already */
};

/* --- Transport operations --- */

struct txfile { const char *env; const char *name; };

typedef struct txport_ops {
  struct txport_ops *next;
  const char *name;
  const struct txfile *fv;
  const char *config;
  txport *(*create)(const char */*file*/);
  int (*configure)(txport */*tx*/, const char */*k*/, const char */*v*/);
  void *(*fetch)(void */*txv*/);
  ssize_t (*write)(txport */*tx*/, const void */*p*/, size_t /*sz*/);
  void (*destroy)(txport */*tx*/);
} txport_ops;

/*----- Global variables --------------------------------------------------*/

extern txport_ops *txlist;
extern const char *txname;
extern const char *txfile;
extern const char *txconf;

#define DIRVAR "JOGDIR"

/*----- Functions provided ------------------------------------------------*/

/* --- @tx_create@ --- *
 *
 * Arguments:	@const char *name@ = name of transport to instantiate
 *		@const char *file@ = filename for transport
 *		@const char *config@ = config string
 *
 * Returns:	A pointer to the transport context, or null on error.
 *
 * Use:		Creates a new transport.
 */

extern txport *tx_create(const char */*name*/, const char */*file*/,
			 const char */*config*/);

/* --- @tx_configure@ --- *
 *
 * Arguments:	@txport *tx@ = pointer to transport block
 *		@const char *config@ = config string
 *
 * Returns:	Zero if OK, nonzero on errors.
 *
 * Use:		Applies a configuration string to a transport.
 */

extern int tx_configure(txport */*tx*/, const char */*config*/);

/* --- @tx_write@ --- *
 *
 * Arguments:	@txport *tx@ = pointer to transport context
 *		@const void *p@ = pointer to buffer to write
 *		@size_t sz@ = size of buffer
 *
 * Returns:	Zero if OK, or @-1@ on error.
 *
 * Use:		Writes some data to a transport.
 */

extern int tx_write(txport */*tx*/, const void */*p*/, size_t /*sz*/);

/* --- @tx_printf@ --- *
 *
 * Arguments:	@txport *tx@ = pointer to transport context
 *		@const char *p@ = pointer to string to write
 *
 * Returns:	The number of characters printed, or @EOF@ on error.
 *
 * Use:		Writes a textual message to a transport.
 */

extern int tx_vprintf(txport */*tx*/, const char */*p*/, va_list */*ap*/);

extern int tx_printf(txport */*tx*/, const char */*p*/, ...);

/* --- @tx_newline@ --- *
 *
 * Arguments:	@txport *tx@ = pointer to transport context
 *
 * Returns:	Zero if OK, nonzero on error.
 *
 * Use:		Writes a newline (record boundary) to the output.
 */

int tx_newline(txport */*tx*/);

/* --- @tx_read@, @tx_readx@ --- *
 *
 * Arguments:	@txport *tx@ = pointer to transport context
 *		@unsigned long t@ = time to wait for data (ms)
 *		@int (*filter)(const char *s, void *p)@ = filtering function
 *		@void *p@ = pointer argument for filter
 *
 * Returns:	A pointer to a line block, which must be freed using
 *		@tx_freeline@.
 *
 * Use:		Fetches a line from the buffer.  Each line is passed to the
 *		filter function in oldest-to-newest order; the filter
 *		function returns nonzero to choose a line.  If no suitable
 *		line is waiting in the raw buffer, the program blocks while
 *		more data is fetched, until the time limit @t@ is exceeded,
 *		in which case a null pointer is returned.  A null filter
 *		function is equivalent to one which always selects its line.
 */

#define FOREVER (~0ul)

extern txline *tx_readx(txport */*tx*/, unsigned long /*t*/,
			int (*/*filter*/)(const char */*s*/, void */*p*/),
			void */*p*/);

extern txline *tx_read(txport */*tx*/, unsigned long /*t*/);

/* --- @tx_freeline@ --- *
 *
 * Arguments:	@txline *l@ = pointer to line
 *
 * Returns:	---
 *
 * Use:		Frees a line block.
 */

extern void tx_freeline(txline */*l*/);

/* --- @tx_destroy@ --- *
 *
 * Arguments:	@txport *tx@ = transport context
 *
 * Returns:	---
 *
 * Use:		Destroys a transport.
 */

extern void tx_destroy(txport */*tx*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif