/*++
*******************************************************************************
* Copyright (c) 1990-97 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:

   DsApi.h

Abstract:

   This header file defines the Digi STREAMS Kernelmode Client API presented by
   the Digi STREAMS API Kernel Library.

   Digi STREAMS client drivers should use the library functions exposed by this
   header file to access Digi STREAMS service providers.

Author:

   Michael Zarns

--*/
#ifndef _DSAPI_
#define _DSAPI_

#include "DgDevice.h"	// Required for DIGI_STATUS macro
#include "dsioctl.h"

///////////////////////////////////////////////////////////////////////////////
//
// Constants
//

// NTSTATUS type Status Values
// Error - bad device state
#define STATUS_DSAPI_DEVICESTATE		DIGI_STATUS( DIGI_ERROR, DIGI_FAC_DSAPI, 1 )
// Error - bad stream state
#define STATUS_DSAPI_STREAMSTATE		DIGI_STATUS( DIGI_ERROR, DIGI_FAC_DSAPI, 2 )


#if 0
// Flags used in the DS_PURGE Mask field defining which queues should be 
// purged.  These Purge constants are duplicated in DsIoctl.h!  If you change 
// them here, be sure to update DsIoctl.h!
#define DS_PURGE_WRITE    0x00000001
#define DS_PURGE_READ     0x00000002
#define DS_PURGE_PUTMSG   0x00000004
#define DS_PURGE_GETMSG   0x00000008
#define DS_PURGE_ALL      0x0000000F
#endif



///////////////////////////////////////////////////////////////////////////////
//
// Prototypes
//


//
// The following APIs complete synchronously and may only be called at IRQL
// PASSIVE_LEVEL.  However, all data passed in must be allocated from NonPagedPool.
//

NTSTATUS 
DsOpenDevice(
	IN PUNICODE_STRING pDeviceName,
	OUT PHANDLE        phDevice );

NTSTATUS 
DsOpenDeviceInternal(
	IN PDEVICE_OBJECT pDeviceObject,
	OUT PHANDLE       phDevice );

NTSTATUS	
DsCloseDevice(
	IN HANDLE hDevice );

NTSTATUS 
DsOpen( 
	IN HANDLE   hDevice,
	IN PCSZ     pcszStreamDeviceName,
	IN HANDLE   hOwner,
	IN PVOID    pUserData OPTIONAL,
	IN ULONG    cbUserData,
	OUT PHANDLE phStream,
	OUT PULONG  pError );

NTSTATUS
DsClose(
	IN HANDLE hStream );

NTSTATUS
DsIoctl(
	IN HANDLE  hStream,
	IN ULONG   Command,
	IN PVOID   pData,
	IN ULONG   DataLength,
	OUT PULONG pErrorCode );

NTSTATUS
DsLink(
	IN HANDLE  hTopStream,
	IN HANDLE  hBottomStream,
	OUT PULONG pMuxId,
	OUT PULONG pErrorCode );

NTSTATUS
DsPush(
	IN HANDLE  hStream,
	IN PCSZ    pcszModuleName,
	OUT PULONG pErrorCode );

NTSTATUS
DsPurge( 
	IN HANDLE hStream, 
	IN ULONG  PurgeFlags );

NTSTATUS
DsGetInfo( 
	IN HANDLE hStream, 
	IN OUT PDS_GETINFO pInfo );

NTSTATUS
DsPutMsg(
	IN HANDLE      hStream,
	IN PVOID       pControlBuffer,
	IN ULONG       ControlLength,
	IN PVOID       pDataBuffer,
	IN ULONG       DataLength,
	IN DS_PRIORITY Priority );

NTSTATUS
DsGetMsg(
	IN HANDLE      hStream,
	IN PVOID       pControlBuffer,
	IN ULONG       ControlMaxLength,
	OUT PULONG     ControlLength,
	IN PVOID       pDataBuffer,
	IN ULONG       DataMaxLength,
	OUT PULONG     DataLength,
	IN DS_PRIORITY Priority );

//
// Client Completion Routines.  These define the completion routine function
// pointers passed into the Asynchronous APIs below.
//

typedef VOID 
	(*PDSL_OPEN_COMPLETION_ROUTINE) ( 
		IN HANDLE   hOwner,
		IN HANDLE   hStream,
		IN ULONG    ErrorCode,
		IN NTSTATUS IoStatus );

typedef VOID 
	(*PDSL_CLOSE_COMPLETION_ROUTINE) ( 
		IN HANDLE   hOwner,
		IN NTSTATUS IoStatus );

typedef VOID 
	(*PDSL_PUTMSG_COMPLETION_ROUTINE) ( 
		IN HANDLE   hOwner,
		IN HANDLE   Context,
		IN PVOID    pControlBuffer,
		IN ULONG    ControlLength,
		IN PVOID    pDataBuffer,
		IN ULONG    DataLength,
		IN NTSTATUS IoStatus );

typedef VOID 
	(*PDSL_GETMSG_COMPLETION_ROUTINE) ( 
		IN HANDLE   hOwner,
		IN HANDLE   Context,
		IN PVOID    pControlBuffer,
		IN ULONG    ControlLength,
		IN PVOID    pDataBuffer,
		IN ULONG    DataLength,
		IN NTSTATUS IoStatus );

//
// The following "Ex" APIs complete asynchronously and may be called at IRQL 
// DISPATCH_LEVEL.  All data passed in must be allocated from NonPagedPool.
//

NTSTATUS
DsOpenEx( 
	IN HANDLE hDevice,
	IN PCSZ   pszStreamDeviceName,
	IN HANDLE hOwner,
	IN PVOID  pUserData OPTIONAL,
	IN ULONG  cbUserData,
	IN PDSL_OPEN_COMPLETION_ROUTINE OpenComplete );

NTSTATUS
DsCloseEx(
	IN HANDLE hStream,
	IN PDSL_CLOSE_COMPLETION_ROUTINE CloseComplete );

NTSTATUS
DsPutMsgEx(
	IN HANDLE      hStream,
	IN PVOID       pControlBuffer,
	IN ULONG       ControlLength,
	IN PVOID       pDataBuffer,
	IN ULONG       DataLength,
	IN HANDLE      Context,
	IN DS_PRIORITY Priority,
	IN PDSL_PUTMSG_COMPLETION_ROUTINE PutMsgComplete );

NTSTATUS
DsGetMsgEx(
	IN HANDLE      hStream,
	IN ULONG       ControlMaxLength,
	IN PVOID       pDataBuffer,
	IN ULONG       DataMaxLength,
	IN HANDLE      Context,
	IN DS_PRIORITY Priority,
	IN PDSL_GETMSG_COMPLETION_ROUTINE GetMsgComplete );

#endif // _DSAPI_