mnmainlp.h

ICCP Toolkit 是在 Tru64下开发Tase.2通信协议的开发包

/*                                SPECTRUM: C                            txt off
 * Copyright (C) Siemens AG 1993 All Rights Reserved.Confidential
 * @BASE-SYS_C   general tasking
 *
 * $Id: mnmainlp.h,v 1.000.1.08 1997/11/21 00:39:39 tome Exp $
 *
 * $NewRev$
 * $NewRevEnd$
 *
 * $Log: mnmainlp.h,v $
 *
 * revision 02/07/00 add uWinMessageHandler
 * revision 03/05/99 add AXS4ICCP check by nav @ sisco
 *
 * Revision 1998/01/14 SISCO Inc: Port to SUN Solaris v2.5 for SPARC wokstation.
 *
 * Revision 1.000.1.08  1997/11/21  00:39:39  tome
 *  EMP14487
 * Change type HANDLE to MnHandle to avoid compilation errors on NT.
 *
 * Revision 1.000.1.07  1997/11/06  17:16:45  tome
 * Add support for Windows NT objects. EMP14487
 *
 * Revision 1.000.1.06  1997/03/25  23:33:21  shri
 * NT Changes EMP12684
 *
 * Revision 1.000.1.05  1997/02/20  00:12:36  charris
 *  EMP12113
 * EMP12113 Fix Unix signal handling.
 *          Add MnReuseTimeOut () function.
 *
 * Revision 1.000.1.04  1996/09/20  19:22:44  hwhite
 *  EMP10398
 * EMP10398 Added definitions for UNIX signal handlers.
 *
 * Revision 1.000.1.03  1996/03/11  23:04:22  sbecchet
 * Add changes for DSI (Distributed System Infrastructure)
 * See src/comms/dsi EMP7147
 *
 * Revision 1.000.1.02  1995/09/25  22:14:02  bwee
 *  EMP5297
 * 950925 bwee: Added modules MnSetDefaultServiceHandler
 * and MnRemoveDefaultServiceHandler. EMP5297
 *
 * Revision 1.000.1.01  1995/08/25  20:44:05  bjmao
 * Add define 'ICAPI' to seperate the Spectrum specific stuff (e.g.
 * softbus, services, objects, and etc.).  With ICAPI defined,
 * mnmainloop can be used independent of Spectrum.  This is used to
 * build the ICCP SDK product. EMP4848
 *
 * Revision 1.000.1.00  1995/08/25  20:28:09  bjmao
 * Create branch for development.
 *
 * Revision 1.000.0.03  1994/09/12  17:38:55  ezeiser
 * Add C++ compatibility
 *
 * Revision 1.000.0.02  1993/07/06  06:45:22  spec
 * take over Spectrum 1.5.1
 *
 * Revision 1.000.0.01  1993/07/03  01:22:35  spec
 * AIX porting
 *
 * $Logend$
 *                                                                       txt on-
 */

#ifndef __MnMainLoop_H
#define __MnMainLoop_H

/*
   Define type MnHandle for Windows NT handle types.  This is used
   instead of the standard Windows NT type HANDLE in order to avoid
   compilation errors.  Here's the reason (you won't believe this).
   The definition of HANDLE comes from file winnt.h, so you need to
   #include that file to use type HANDLE.  Unfortunately, you are not
   allowed to #include winnt.h if you are using MFC (Microsoft
   Foundation Classes) with C++.  (It gives a compilation error which
   tells you that explicitly.)  The only solution seemed to be to
   create our own type, MnHandle, which is identical to HANDLE, but
   doesn't require us to call in winnt.h to access it.
*/

#ifdef _WIN32
typedef void *MnHandle;
#endif

#ifdef _WIN32
typedef enum mnLoop
{ /* Specifies type of loop control. */
    mnReturn,
    mnLoopForever,
    mnQuit
} mnLoop;
#else
#define mnLoopForever            (1)
#endif

/* 
 * The ICAPI is used to seperate the Spectrum related stuff (e.g. softbus,
 * services, objects, and etc.) within mnmainloop.   With ICAPI defined, 
 * mnmainloop can be used independent of Spectrum.  This was initially
 * done for the ICCP SDK product.  It is now also used for the DSI
 * product.
 *
 * Ensure that ICAPI is always defined on NT platforms.  This is
 * because there are some non-ICCP applications on NT which use
 * mainloop, and we don't want them to have to define ICAPI
 * themselves.
 */

#if defined(_WIN32) && ! defined(ICAPI)
#define ICAPI
#endif



/* SISCO_START 	*/
#define icMainLoop	MnMainLoop
/* SISCO_END	*/



#ifndef _WIN32
#define boolean   unsigned char
#endif

#define mnMainLoop               MnMainLoop
#define mnAddTimeOutHandler      MnAddTimeOutHandler
#define mnRemoveTimeOutHandler   MnRemoveTimeOutHandler
#define mnRestartTimeOut         MnRestartTimeOut
#define mnReuseTimeOut           MnReuseTimeOut
#define mnSetEventHandler        MnSetEventHandler
#define mnRemoveEventHandler     MnRemoveEventHandler


/* A background task has user data specified on a mnAddBackgroundTask call. */

typedef void *mnUserDataType;    /* Any user information that fits in void*. */

typedef void (*mnBackgroundType) ( /* Form of background task. */
      mnUserDataType
);
 
/* FILE START
*******************************************************************************

NAME
    mnmainloop.h - Defines types and functions for user interface
                   to MnMainLoop procedures.

SCOPE
    External to subsystem.

SYNOPSIS
    For SPECTRUM:
    #include <def_c/mnmainloop.h>

    For others AIX enviromnents:
    #include <mnmainloop.h>

DESCRIPTION
    Defines MnMainLoop, MnSetEventHandler, MnRemoveEventHandler,
MnSetObjectHandler, MnSetServiceHandler, MnSetRequestHandler,
MnRemoveObjectHandler, MnRemoveServiceHandler, MnRemoveRequestHandler,
MnAddTimeOutHandler, MnRemoveTimeOutHandler, MnReuseTimeOut, and
MnRestartTimeOut.

NOTES
For users of the ICCP SDK, only the following functions are MnMainLoop,
MnAddTimeOutHandler, MnRemoveTimeOutHandler, MnRestartTimeOut.  
For AIX, MnSetEventHandler and MnRemoveEventHandler are supported.
For NT, mnAddBackgroundTask and mnRemoveBackgroundTask are supported.

When compiling a program that includes this header file, the user
must include /DICAPI in the compile statement.
*******************************************************************************
FILE END */

#ifndef _WIN32
#include <sys/time.h>
#endif /* _WIN32 */

#ifndef ICAPI
#include <def_c/syx.h>
#include <def_c/sbx.h>
#endif
/* ICAPI */

#ifdef __cplusplus
extern "C" {
#endif

/* Types used by prototypes. */

typedef enum mnConditionType
{   /* Specifies which select condition is desired.  When in doubt,
       use mnRead (correct except in a few cases of system services). */

    mnRead,                /* Data available for read. */
    mnWrite,               /* Write completed (pipe empty). */
    mnException            /* Exception condition. */
}    mnConditionType;

/* An I/O event handler has two parameters.  The first passes user data
specified on a MnSetEventHandler call.  The second passes the fid that
has the I/O condition. */

typedef void (*mnEventHandlerType)(    /* Form of event handler. */
    mnUserDataType,
    int        fid
);

/* FORTRAN callable version
 *
 *  call MnFtnEventHandler (userData, fid)
 *  "pointer to any thing" userData
 *  integer fid
 *
 */


/* A softbus event handler has three parameters.  The first passes the
softbus order.  The second passes user data specified on a
MnSetObjectHandler, MnSetServiceHandler, or MnSetRequestHandler call.
The third passes SbFlags returned from a softbus SbReceivO call. */

typedef void (*mnSbHandlerType)(    /* Form of softbus handler. */
    void       *sbOrder,
    mnUserDataType,
    int        sbFlags
);

/* FORTRAN callable version
 *
 *  call MnFtnSbHandler (sbOrder, userData, sbFlags)
 *  "pointer to" sbOrder
 *  "pointer to any thing" userData
 *  integer sbFlags
 *
 */


typedef void *mnTimerIdType;    /* Type of a TimerId. */


/* A TimeOut handler has two parameters.  The first passes user data
specified on a MnAddTimeOutHandler call.  The second passes the
TimerId of the timer that has timed out. */

typedef void (*mnTimeOutHandlerType)( /* Form of TimeOut event handler. */
    mnUserDataType,
    mnTimerIdType   TimerId
);

/* FORTRAN callable version
 *
 *  call MnFtnTimeOutHandler (userData, TimerId)
 *  "pointer to any thing" userData
 *  integer TimerId
 *
 */

#ifdef _WIN32
/* A background task has user data specified on a mnAddBackgroundTask
call. */

typedef void (*mnBackgroundType) ( /* Form of background task. */
 mnUserDataType
);
#endif

/* The type of a Windows NT event handler function. */

#ifdef _WIN32
typedef void (*mnWinNtObjectHandlerType)
    (MnHandle objectHandle, mnUserDataType userData);
#endif

/* FUNCTION START
*******************************************************************************

NAME

    MnMainLoop - look for I/O events and call event handlers.


SYNOPSIS

    #include <def_c/mnmainloop.h>

  
*******************************************************************************
*/
#ifndef _WIN32
#ifdef __STDC__
boolean MnMainLoop(
    boolean    loopForever,
    struct timeval    *timeout);
#else
boolean MnMainLoop();
#endif

#else /* it is WIN32 */
extern void MnMainLoop(
    mnLoop      loopControl);
#endif /* _WIN32 */
/*
*******************************************************************************

FORTRAN callable version

    call MnFtnMainLoop (loopForever, tsecs, tusecs, timeOut)
    logical loopForever
    integer tsecs
    integer tusecs
    logical timeOut


DESCRIPTION

    MnMainLoop detects I/O, softbus orders, and timeout events, calls
the desired event handlers and either loops forever or returns
immediately.

    If loopForever is TRUE then MnMainLoop loops on calling select and
the desired event handlers.  If no timers are registered then select is
called to wait until the next I/O event or softbus order.  If timers
are registered then the select call includes the time until the next
timer expires or one second, which ever is sooner.  Any pending softbus
orders are received and the desired event handlers are called.  The
return from select is decoded and the desired I/O event handlers are
called.  If a time period expires then the desired timeout event
handlers are called.

    If loopForever is FALSE then MnMainLoop calls select once, receives
any softbus orders, calls desired event handlers and returns.  If no
timers are registered then select is called with the user supplied
timeout.  If timers are registered, then the select call includes the
time until the next timer expires, one second, or the user supplied
timeout, which ever is sooner.  Any pending softbus orders are received
and the desired event handlers are called.  If select located I/O
events, then the return from select is decoded, the desired event
handlers are called and MnMainLoop returns indicating no select
timeout.  If timeout is for one second, then MnMainLoop returns
indicating no select timeout.  If timeout is for the next timer, then
the desired timeout event handlers are called and MnMainLoop returns
indicating no select timeout.  If timeout is for the user supplied
timeout, then MnMainLoop returns and indicates select timed out.

INPUT VALUES

    loopForever - specifies if the caller wants control back.  If FALSE
                  then control is returned if no I/O events are found.
                  If TRUE then this procedure loops forever.

    timeout - pointer to an array of type timeval.  If the pointer is
              NULL then select will not return until an I/O event
              occurs.  If the timeout seconds and microseconds are zero
              then select returns immediately after checking for I/O
              events.  Otherwise, select will delay until an I/O event
              occurs, a softbus order is sent (signal SIGUSR1 is sent)
              or timeout specified time has past.

OUTPUT VALUES

    return value - TRUE if a time out occured on the select call.  FALSE if
                   no time out occured.

NOTES

    MnMainLoop timers are only periodic in nature.  The expiration is
processed within the limits of the underlying system.  For example, a
one second expiration might be delayed for several tenths of a second
by other processes executing on the same system.

    MnMainLoop assumes that processes need to make up for small
occurances of expiration delay.  For example, a .2 second delay on a .5
seond timer is made up by next calling the user timeout handler in .3
seconds.  The user calls MnRestartTimeOut if making up for the delay is
not desired.

    UNIX does not provide a true elapsed time capability, therefore,
periodic timers are based on time of day.  Operational changes in time
of day such as day light savings time and leap year must be detected.
Any change in time forward by more than 10 seconds or backward by 1
second is assumed to be an operational time change.  An approximation
of elapsed time must then be made, i.e. one second has passed.

    Use SbAlarm if your process has timer demands not met by the
above criteria.

NOTES from NT version of function:
------------------
mnMainLoop detects I/O and timeout events, calls the desired event
handlers and either loops forever or returns immediately.

mnMainLoop executes one of the following algorithms based on the
existing conditions.

a) Conditions: mnLoopForever, no timers, no background task.
   Call sleepEx to sleep until the next I/O event.
   Loop.

b) Conditions: mnLoopForever, no timers, background tasks.
   Call sleepEx to sleep until the next I/O event.
   Call background task.
   Loop.

c) Conditions: mnLoopForever, timers, no background tasks. 
   If a time period expires then the desired timeout event handlers are
   called.
   Call sleepEx to sleep until the next I/O event or the time until the
   next timer expires, which ever is sooner.
   Loop. 

d) Conditions: mnLoopForever, timers, background tasks. 
   If a time period expires then the desired timeout event handlers are
   called.
   Call background task.
   If a time period expires then the desired timeout event handlers are
   called.
   Call sleepEx to sleep until the next I/O event or the time until the
   next timer expires, which ever is sooner.
   Loop. 
   
e) Conditions: mnReturn, no timers, no background task. 
   Call sleepEx to sleep until the next I/O event.
   Return to caller.

f) Conditions: mnReturn, no timers, background tasks. 
   Call sleepEx with an immediate return. 
   Call background task. 
   Call sleepEx to sleep until the next I/O event.
   Return to caller.

g) Conditions: mnReturn, timers, no background tasks. 
   If a time period expires then the desired timeout event handlers are
   called.
   Call sleepEx to sleep until the next I/O event or the time until the
   next timer expires, which ever is sooner.
   If a time period expires then the desired timeout event handlers are
   called.
   Return to caller.

h) Conditions: mnReturn, timers, background tasks. 
   Call sleepEx with an immediate return.
   If a time period expires then the desired timeout event handlers are
   called and loop. 
   Call background task.
   If a time period expires then the desired timeout event handlers are
   called.
   Call sleepEx to sleep until the next I/O event or the time until the
   next timer expires, which ever is sooner.
   If a time period expires then the desired timeout event handlers are
   called.
   Return to caller.
   
INPUT VALUES
 loopControl - specifies if the caller wants control back.
               If mnReturn then control is returned after looking for
               timers and I/O events (see description).
               If mnLoopForever then this procedure loops forever.
    
OUTPUT VALUES

    none


If mnReturn is specified then mnMainLoop should be repeatedly called
to check for timers and I/O events.
------------------
*
*******************************************************************************
FUNCTION END */



/* FUNCTION START
*******************************************************************************

NAME

    MnSetEventHandler - Set event handler to be called when I/O event
occurs on specified file descriptor and condition.  Only one event
handler is active at a time per file descriptor and condition.


SYNOPSIS

    #include <def_c/mnmainloop.h>

NOTES
This is not supported in the NT version of this library.
*******************************************************************************
*/
#ifndef _WIN32
#ifdef __STDC__
void MnSetEventHandler(
    int        fid,
    mnConditionType    condition,
    mnEventHandlerType    eventHandler,
    mnUserDataType    userData);
#else
void MnSetEventHandler();
#endif
#endif /* _WIN32 */

/*
*******************************************************************************

FORTRAN callable version

    call MnFtnSetEventHandler (fid, condition, ftnFunc, userData)
    integer fid
    integer condition
    function ftnFunc
    "pointer to any thing" userData


DESCRIPTION

    The MnSetEventHandler procedure sets an event handler to be called
when an I/O event occurs for the specified file descriptor and condition.

INPUT VALUES

    fid - file descriptor.

    condition - type of select I/O event.

    eventHandler - event handler.

    userData - user data (anything that is the same size as a pointer).

OUTPUT VALUES