/*++
*******************************************************************************
* Copyright (c) 1999-2000 Digi International Inc., All Rights Reserved        *
*                                                                             *
* This software contains proprietary and confidential information of Digi     *
* International Inc.  By accepting transfer of this copy, Recipient agrees    *
* to retain this software in confidence, to prevent disclosure to others,     *
* and to make no use of this software other than that for which it was        *
* delivered.  This is an unpublished copyrighted work of Digi International   *
* Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly   *
* prohibited.                                                                 *
*                                                                             *
* Restricted Rights Legend                                                    *
*                                                                             *
* Use, duplication, or disclosure by the Government is subject to             *
* restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in         *
* Technical Data and Computer Software clause at DFARS 252.227-7031 or        *
* subparagraphs (c)(1) and (2) of the Commercial Computer Software -          *
* Restricted Rights at 48 CFR 52.227-19, as applicable.                       *
*                                                                             *
* Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343          *
*                                                                             *
*******************************************************************************

Module Name:

   asynrx.h

Abstract:

   Public api for the receive (rx) engine.

Author:

   Michael Zarns

--*/
#ifndef ASYNRX_H
#define ASYNRX_H

///////////////////////////////////////////////////////////////////////////////
//
// Data structures needed by rx engine
//
///////////////////////////////////////////////////////////////////////////////
//
// Two types of data messages come up from the card - data only, and control data
// messages.  We have a different callback routine for each.  In both cases,
// the callback routine is responsible for freeing the data buffer passed up using
// RxEngineFreeData.  
//
// The control portion in Control Data messages is owned by the rxengine and should
// never be freed by the caller.  It can only be assumed valid until returning from
// the OnCdata handler.
//
///////////////////////////////////////////////////////////////////////////////


// Callback routine for Data only messages
typedef void (*PASYN_RXENGINE_DATA_HANDLER) ( HANDLE Context, PVOID pData, ULONG cbData );

// Callback routine for Control+Data messages
typedef void (*PASYN_RXENGINE_CDATA_HANDLER)( HANDLE Context, PVOID pCtrl, ULONG cbCtrl, PVOID pData, ULONG cbData );

// Callback routine for Cleanup (on error)
typedef void (*PASYN_RXENGINE_CLEANUP_HANDLER)(HANDLE Context, NTSTATUS IOStatus);

// RxEngine data struct.  
typedef struct 
{
    HANDLE      hStream;				// Dsapi Stream on which to run
    ULONG       nGetMsgMax;			// Max number of simultaneous GetMsg requests
    ULONG       nGetMsgPending;	// Count of outstanding GetMsg requests
    BOOLEAN     fPaused;				// Flag used to pause the rxengine.
    BOOLEAN     fHalt;				// Flag used to halt the rxengine.
    ULONG       cbMaxCtrl;			// Default Max size of control buffer
    ULONG       cbMaxData;			// Default Max size of data buffer
    ULONG       cbDataHeader;		// Pad bytes in front of cbMaxData in data buffer
    DS_PRIORITY Priority;			// DStream priority at which to send GetMsg requests
    HANDLE      hOwner;				// Context returned in the OnData callbacks
    KEVENT      Stopped;				// Event used when halting the rxengine
    BOOLEAN		fInitialized;		// Flag used to initialize structures once instead on each RxEngineStart
    KDPC        Dpc;					// DPC for firing off getmsg requests
    KTIMER      Timer;				// Timer coupled with DPC
    DIGI_SPINLOCK Lock;

    PASYN_RXENGINE_DATA_HANDLER  pOnData;	// Callback for data only messages
    PASYN_RXENGINE_CDATA_HANDLER pOnCdata;	// Callback for control/data messages
    PASYN_RXENGINE_CLEANUP_HANDLER pOnCleanup;  // Callback for cleanup
} ASYN_RXENGINE, *PASYN_RXENGINE;

 
///////////////////////////////////////////////////////////////////////////////
//
// The rx engine API
//
///////////////////////////////////////////////////////////////////////////////
//
// The receive engine will purge any incoming messages larger than cbMaxControl
// (for the control portion) and cbMaxData (for the data portion).  Be sure to
// specify an accurate maximum for each!
//
// Note: SDXB allows you to set the max data buffer length using the maxlen field in
// the sdxb_param_command struct.
//
///////////////////////////////////////////////////////////////////////////////

// Start a RxEngine
HANDLE RxEngineStart( 
    IN HANDLE                       hStream, 		// Stream on which to post getmsgs 
    IN HANDLE                       hOwner, 		// Handle passed into callbacks
    IN PASYN_RXENGINE_DATA_HANDLER  pOnData,		// Handler for data-only messages
    IN PASYN_RXENGINE_CDATA_HANDLER pOnCdata,		// Handler for control-data messages
    IN PASYN_RXENGINE_CLEANUP_HANDLER pOnCleanup,   // Handler for cleanup
    IN ULONG                        cbMaxControl,// Max buffersize for control portion
    IN ULONG                        cbMaxData,	// Max buffersize for data portion
    IN ULONG                        cbDataHeader,// Padding in front of data portion
    IN ULONG                        nGetMsgRequests,// Max number of requests to pend
    IN DS_PRIORITY                  Priority );

// Tell the engine to temporarily stop sending GetMsg requests.
VOID RxEnginePause( IN HANDLE hEngine );

// Tell the engine to restart sending GetMsg requests after a Pause.
VOID RxEngineUnpause( IN HANDLE hEngine );


// Kills the engine.  Do this before closing the dxb stream for this port.
VOID RxEngineStop( IN HANDLE hEngine );

// OnData and OnCdata callbacks are responsible for freeing the data buffer.
// Use FreeData to do so.
VOID RxEngineFreeData( IN PVOID pData );

#endif
