//
// ac_fdio.h - file descriptor io functions
//
// Copyright (C) 2006  Nathan (Acorn) Pooley
// 
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// version 2 as published by the Free Software Foundation.
// 
// This program 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 (gpl.txt) for more details. 
// 
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
// 
// You can contact the author, Nathan (Acorn) Pooley, by writing
// to Nathan (Acorn) Pooley, 949 Buckeye Drive, Sunnyvale, CA  94086, USA
// or through the form at http://www.rawbw.com/~acorn/wand/feedback.html
//
//
// Thanks to Gary Frerking for writing the Serial Programming HOWTO at
//    http://www.tldp.org/HOWTO/Serial-Programming-HOWTO
// Much of this is based on his descriptions and examples.
//
#ifndef AC_FDIO_H
#define AC_FDIO_H

//#@DOC@ file descriptor io functions

//###########################################################################
//############################### NOTES #####################################
//###########################################################################
//
//  H   H   OOO   W   W        TTTTT   OOO        U   U   SSSS  EEEE
//  H   H  O   O  W W W          T    O   O       U   U  S      E
//  HHHHH  O   O  W W W          T    O   O       U   U   SSS   EEE
//  H   H  O   O  WWWWW          T    O   O       U   U      S  E
//  H   H   OOO    W W           T     OOO         UUU   SSSS   EEEEE
//
// 1) Create a group with
//     AcFdGroup *g = AcFdGroupCreate();
//
// 2) Add 1 or more file descriptors (with func & data) with:
//     AcFdGroupAdd(g, fd, func, data);
//
// 3) Start loop with
//     AcFdGroupLoop(g);
//
//  Whenever chars are available on a file descriptor, the associated function
//  will be called.  If the function returns nonzero the loop ends.
//
//  OTHER INFO
//  ----------
//
//  Use AcFdGroupWait() instead of AcFdGroupLoop() to just loop once
//  If a fd becomes readable, one of the handler functions is called and its
//  return value is returned.
//  If a timeout occurs -2 is returned.
//  If an error occurs -1 is returned.
//
//  Use AcFdGroupWaitTimeout() instead of AcFdGroupLoop() to just loop once
//  with a timeout (in microseconds).  Use usecTimeout==0 to return immediately.
//  If a fd becomes readable, one of the handler functions is called and its
//  return value is returned.
//  If a timeout occurs -2 is returned.
//  If an error occurs -1 is returned.
//
//  To remove an entry from grp, call:
//     AcFdGroupRemove(grp, fd, func, data);
//  Any matches with fd, func, and data will be removed.
//  fd<0, func==0, and data==0 indicate match-any.
//
//
//  Use AcFdGroupSetTimeout() to set a timeout.  Use sec==usec==0 for
//  immediate return.  Use AcFdGroupClearTimeout() to turn timeout off so
//  AcFdGroupWait() waits forever (this is the default)
//

//###########################################################################
//############################### TYPEDEFS ##################################
//###########################################################################

//===========================================================================
// AcFdFunc - function to read fd
//===========================================================================
// returns 0 to continue loop; nonzero to exit loop
typedef int (*AcFdFunc)(int fd, void *data);

typedef struct AcFdGroupRec AcFdGroup;

//###########################################################################
//############################### PROTOTYPES ################################
//###########################################################################

AcFdGroup *AcFdGroupCreate(void);
void       AcFdGroupDestroy(AcFdGroup *grp);

int AcFdGroupAdd(AcFdGroup *grp, int fd, AcFdFunc func, void *data);
int AcFdGroupRemove(AcFdGroup *grp, int fd, AcFdFunc func, void *data);

int   AcFdGroupWait(AcFdGroup *grp);
int   AcFdGroupWaitTimeout(AcFdGroup *grp, unsigned long usecTimeout);
int   AcFdGroupLoop(AcFdGroup *grp);

void AcFdGroupSetTimeout(AcFdGroup *grp, long sec, long usec);
void AcFdGroupClearTimeout(AcFdGroup *grp);


#endif // AC_FDIO_H