448 lines
15 KiB
C++
448 lines
15 KiB
C++
/*
|
|
* tptif.h
|
|
*
|
|
* Copyright (c) 1993 - 1995 by DataBeam Corporation, Lexington, KY
|
|
*
|
|
* Abstract:
|
|
* This is the interface file for the TransportInterface class.
|
|
* This class provides a seamless interface to the TCP transport stack.
|
|
*
|
|
* The public interface of this class includes a member function for each
|
|
* of the API routines that a user application would need to call. The
|
|
* only API routines not directly accessible are those used for
|
|
* initialization and cleanup (which are automatically executed in the
|
|
* constructor and destructor, respectively). When a user application
|
|
* needs to call one of the available API routines, it merely calls the
|
|
* equivalent member function within the proper instance of this class.
|
|
* The API routine will then be invoked using the same parameters.
|
|
*
|
|
* The destructor calls the cleanup routine within the DLL for which it is
|
|
* responsible.
|
|
*
|
|
* The management plane functions include support for initialization and
|
|
* setup, as well as functions allowing MCS to poll the transport
|
|
* interfaces for activity.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*
|
|
* Author:
|
|
* James P. Galvin, Jr.
|
|
*/
|
|
#ifndef _TRANSPORTINTERFACE_
|
|
#define _TRANSPORTINTERFACE_
|
|
|
|
#include "tprtsec.h"
|
|
|
|
/*
|
|
* This typedef defines the errors that can be returned from calls that are
|
|
* specific to TransportInterface classes. Note that the public member
|
|
* functions that map to transport stack calls do not return an error of this
|
|
* type. Rather, they return an error as defined by the transport API (TRAPI).
|
|
*/
|
|
typedef enum
|
|
{
|
|
TRANSPORT_INTERFACE_NO_ERROR,
|
|
TRANSPORT_INTERFACE_INITIALIZATION_FAILED,
|
|
TRANSPORT_INTERFACE_ALLOCATION_FAILED,
|
|
TRANSPORT_INTERFACE_NO_SUCH_CONNECTION,
|
|
TRANSPORT_INTERFACE_CONNECTION_ALREADY_EXISTS
|
|
} TransportInterfaceError;
|
|
typedef TransportInterfaceError * PTransportInterfaceError;
|
|
|
|
|
|
class CTransportConnList2 : public CList2
|
|
{
|
|
DEFINE_CLIST2(CTransportConnList2, PConnection, UINT)
|
|
void AppendEx(PConnection p, TransportConnection XprtConn)
|
|
{
|
|
UINT nKey = PACK_XPRTCONN(XprtConn);
|
|
Append(nKey, p);
|
|
}
|
|
PConnection FindEx(TransportConnection XprtConn)
|
|
{
|
|
UINT nKey = PACK_XPRTCONN(XprtConn);
|
|
return Find(nKey);
|
|
}
|
|
PConnection RemoveEx(TransportConnection XprtConn)
|
|
{
|
|
UINT nKey = PACK_XPRTCONN(XprtConn);
|
|
return Remove(nKey);
|
|
}
|
|
};
|
|
|
|
|
|
/*
|
|
* These are the owner callback messages that a transport interface object
|
|
* can send. They correspond directly to the messages that will be received
|
|
* from the various transport stacks.
|
|
*/
|
|
#define CONNECT_CONFIRM 0
|
|
#define DISCONNECT_INDICATION 1
|
|
#define DATA_INDICATION 2
|
|
#define STATUS_INDICATION 3
|
|
#define BUFFER_EMPTY_INDICATION 4
|
|
#define WAIT_UPDATE_INDICATION 5
|
|
|
|
/*
|
|
* This is simply a forward reference for the class defined below. It is used
|
|
* in the definition of the owner callback structure defined in this section.
|
|
*/
|
|
class TransportInterface;
|
|
typedef TransportInterface * PTransportInterface;
|
|
|
|
/*
|
|
* Owner Callback: CONNECT_CONFIRM
|
|
* Parameter1: Unused
|
|
* Parameter2: TransportConnection transport_connection
|
|
*
|
|
* Usage:
|
|
* This owner callback is sent when a connect confirm is received from
|
|
* the transport layer. This is to inform the recipient that a transport
|
|
* connection is now available for use. Connect confirm will occur
|
|
* on outbound connections. They represent a new transport connection
|
|
* that has resulted from this system calling a remote one. As such,
|
|
* there should always be a registered owner of the transport connection
|
|
* (registration is a side-effect of the call to ConnectRequest).
|
|
*
|
|
* So the connect confirm will be routed to the object that is the
|
|
* registered owner of the transport connection. That object may now
|
|
* utilize the connection to transfer data.
|
|
*/
|
|
|
|
/*
|
|
* Owner Callback: DISCONNECT_INDICATION
|
|
* Parameter1: Unused
|
|
* Parameter2: TransportConnection transport_connection
|
|
*
|
|
* Usage:
|
|
* This owner callback is sent when a disconnect indication is received
|
|
* from the transport layer. This is to inform the recipient that a
|
|
* transport connection is no longer available for use. If an object
|
|
* has explicitly registered itself as the owner of a transport connection,
|
|
* then it will receive the disconnect indication. If there has been no
|
|
* such registration, then the disconnect indication will be sent to the
|
|
* default owner callback.
|
|
*
|
|
* Once a disconnect indication has been issued for a given transport
|
|
* connection, that connection can no longer be used for anything.
|
|
*/
|
|
|
|
/*
|
|
* Owner Callback: DATA_INDICATION
|
|
* Parameter1: PDataIndicationInfo data_indication_info
|
|
* Parameter2: TransportConnection transport_connection
|
|
*
|
|
* Usage:
|
|
* This owner callback is sent when a data indication is received from
|
|
* the transport layer. The transport data structure contains the address
|
|
* and length of the user data field that is associated with the data
|
|
* indication. If an object in the system has explicitly registered
|
|
* ownership of the transport connection that carried the data (either
|
|
* through ConnectRequest or RegisterTransportConnection), then this
|
|
* callback will be sent to that object. If no object has registered
|
|
* this transport connection, then the data will be sent to the default
|
|
* owner.
|
|
*/
|
|
|
|
/*
|
|
* Owner Callback: STATUS_INDICATION
|
|
* Parameter1: PTransportStatus transport_status
|
|
* Parameter2: Unused
|
|
*
|
|
* Usage:
|
|
* This owner callback is just a pass-through of the status indication
|
|
* that comes from the transport layer. It contains a pointer to a
|
|
* transport status structure that contains status information that
|
|
* originated from the stack represented by this object. This is always
|
|
* passed to the default owner object.
|
|
*/
|
|
|
|
/*
|
|
* Owner Callback: BUFFER_EMPTY_INDICATION
|
|
* Parameter1: Unused
|
|
* Parameter2: TransportConnection transport_connection
|
|
*
|
|
* Usage:
|
|
* This owner callback is a pass-through of the buffer empty indication
|
|
* that comes from the transport layer. It is sent to the object that
|
|
* has registered ownership of the specified transport connection. This
|
|
* indication tells that object that the transport layer can now accept
|
|
* more data.
|
|
*/
|
|
|
|
class Connection;
|
|
typedef Connection *PConnection;
|
|
|
|
/*
|
|
* This is the class definition for the TransportInterface class. Remember,
|
|
* this class contains pure virtual functions which makes it an abstract base
|
|
* class. It cannot be instantiated, but rather, exists to be inherited from.
|
|
* These derived classes will implement the behavior that is specific to a
|
|
* particular transport stack (or possibly just the interface to a particular
|
|
* transport stack).
|
|
*/
|
|
class TransportInterface
|
|
{
|
|
public:
|
|
TransportInterface (
|
|
HANDLE transport_transmit_event,
|
|
PTransportInterfaceError
|
|
transport_interface_error);
|
|
~TransportInterface ();
|
|
TransportInterfaceError RegisterTransportConnection (
|
|
TransportConnection transport_connection,
|
|
PConnection owner_object,
|
|
BOOL bNoNagle);
|
|
#ifdef NM_RESET_DEVICE
|
|
TransportError ResetDevice (
|
|
PChar device_identifier);
|
|
#endif // NM_RESET_DEVICE
|
|
TransportError ConnectRequest (
|
|
TransportAddress transport_address,
|
|
BOOL fSecure,
|
|
BOOL bNoNagle,
|
|
PConnection owner_object,
|
|
PTransportConnection
|
|
transport_connection);
|
|
void DisconnectRequest (
|
|
TransportConnection transport_connection);
|
|
void DataRequestReady () {
|
|
SetEvent (Transport_Transmit_Event);
|
|
};
|
|
void ReceiveBufferAvailable ();
|
|
BOOL GetSecurity( TransportConnection transport_connection );
|
|
|
|
PSecurityInterface pSecurityInterface;
|
|
BOOL bInServiceContext;
|
|
TransportInterfaceError CreateConnectionCallback (
|
|
TransportConnection transport_connection,
|
|
PConnection owner_object);
|
|
void ConnectIndication (
|
|
TransportConnection transport_connection);
|
|
void ConnectConfirm (
|
|
TransportConnection transport_connection);
|
|
void DisconnectIndication (
|
|
TransportConnection transport_connection,
|
|
ULONG ulReason);
|
|
TransportError DataIndication (
|
|
PTransportData transport_data);
|
|
void BufferEmptyIndication (
|
|
TransportConnection transport_connection);
|
|
|
|
private:
|
|
|
|
CTransportConnList2 m_TrnsprtConnCallbackList2;
|
|
HANDLE Transport_Transmit_Event;
|
|
};
|
|
|
|
/*
|
|
* TransportInterface (
|
|
* PTransportInterfaceError transport_interface_error)
|
|
*
|
|
* Functional Description:
|
|
* The constructor initializes the TCP transport code.
|
|
*
|
|
* The constructor also includes parameters specifying the default
|
|
* callback. This callback is used to inform the controller whenever an
|
|
* unexpected inbound connection is detected. This gives the controller
|
|
* the opportunity to assign responsibility for the new connection to some
|
|
* other object in the system.
|
|
*
|
|
* If anything goes wrong in the constructor, the return value (whose
|
|
* address is passed as a constructor parameter) will be set to one of the
|
|
* failure codes. If this happens, it is expected that whoever invoked the
|
|
* constructor (probably the controller), will immediately delete the
|
|
* object without using it. Failure to do this WILL result in unexpected
|
|
* behavior.
|
|
*
|
|
* Formal Parameters:
|
|
* default_owner_object (i)
|
|
* This is the address of the object that will handle all transport
|
|
* events for unregistered transport connections. This includes
|
|
* connect indication, dicsonnect indication, and data indication.
|
|
* This object will also receive all state and message indications.
|
|
* default_owner_message_base (i)
|
|
* This is the base value to be used for all owner callback messages.
|
|
* transport_interface_error (o)
|
|
* This is where the return code will be stored so that the creator of
|
|
* this object can make sure that everything is okay before using the
|
|
* new object. If this value is set to anything but success, the
|
|
* object should be destroyed immediately, without being used.
|
|
*
|
|
* Return Value:
|
|
* Note: the return value is handled as a constructor parameter.
|
|
* TRANSPORT_INTERFACE_NO_ERROR
|
|
* Everything worked, and the object is ready for use.
|
|
* TRANSPORT_INTERFACE_INITIALIZATION_FAILED
|
|
* The initialization of the transport interface object failed. It is
|
|
* therefore necessary to destroy the object without attempting to
|
|
* use it.
|
|
*
|
|
* Side Effects:
|
|
* A DLL will be loaded into memory, for later use.
|
|
*
|
|
* Caveats:
|
|
*/
|
|
|
|
/*
|
|
* ~TransportInterface ()
|
|
*
|
|
* Functional Description:
|
|
* The destructor frees up all resources used by the base class. This
|
|
* is primarily associated with the callback list (which is maintained by
|
|
* this class).
|
|
*
|
|
* Formal Parameters:
|
|
* Destructors have no parameters.
|
|
*
|
|
* Return Value:
|
|
* Destructors have no return value.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* TransportInterfaceError RegisterTransportConnection (
|
|
* TransportConnection transport_connection,
|
|
* PConnection owner_object,
|
|
* BOOL bNoNagle)
|
|
*
|
|
* Functional Description:
|
|
* When an inbound connection is detected, an entry is created in the
|
|
* callback list for it using the default owner callback information (that
|
|
* was specified in the constructor). This means that all events detected
|
|
* for the new transport connection will be sent to the default owner
|
|
* object until another object explicitly registers itself as the owner
|
|
* of the transport connection. That is what this routine is used for.
|
|
*
|
|
* Once an object has registered itself as the owner of a transport
|
|
* connection, it will receive all events related to that connection.
|
|
*
|
|
* Formal Parameters:
|
|
* transport_connection (i)
|
|
* This is the transport connection for which the callback information
|
|
* is to be associated.
|
|
* owner_object (i)
|
|
* This is the address of the Connection object that is to receive all transport
|
|
* layer events for the specified transport connection.
|
|
* bNoNagle (i)
|
|
* Should the connection stop using the Nagle algorithm?
|
|
*
|
|
* Return Value:
|
|
* TRANSPORT_INTERFACE_NO_ERROR
|
|
* The operation completed successfully.
|
|
* TRANSPORT_INTERFACE_NO_SUCH_CONNECTION
|
|
* This indicates that the named transport connection does not exist.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* TransportError ConnectRequest (
|
|
* TransportAddress transport_address,
|
|
* BOOL bNoNagle,
|
|
* PConnection owner_object,
|
|
* PTransportConnection transport_connection)
|
|
*
|
|
* Functional Description:
|
|
* This operation is invoked when the user application wishes to establish
|
|
* an outbound connection. Assuming that everything is successful, the
|
|
* owner callback information that is passed in to this operation is saved
|
|
* for later use. All events for this transport connection will be routed
|
|
* to the specified owner rather than the default owner.
|
|
*
|
|
* Formal Parameters:
|
|
* transport_address (i)
|
|
* This is the transport address to be passed to the transport stack
|
|
* during the connection creation process. The format of this address
|
|
* string will vary by transport stack, and cannot be specified here.
|
|
* bNoNagle (i)
|
|
* Do we need to disable the Nagle algorithm?
|
|
* owner_object (i)
|
|
* This is the address of the object that is to receive all transport
|
|
* layer events for the new transport connection.
|
|
* transport_connection (o)
|
|
* This is the address of the variable that is to receive the transport
|
|
* connection handle that is associated with this connection. Note
|
|
* that this handle is assigned before the connection is actually
|
|
* established, to allow the application to abort a connection in
|
|
* progress.
|
|
*
|
|
* Return Value:
|
|
* TRANSPORT_NO_ERROR
|
|
* The operation completed successfully.
|
|
* TRANSPORT_NOT_INITIALIZED
|
|
* The transport stack is not initialized.
|
|
*
|
|
* Side Effects:
|
|
* An outbound connection establishment process is begun in the background.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
/*
|
|
* TransportError DisconnectRequest (
|
|
* TransportConnection transport_connection)
|
|
*
|
|
* Functional Description:
|
|
* This operation is used to break an existing transport connection. If
|
|
* the operation is successful, the transport connection will be removed
|
|
* from the callback list.
|
|
*
|
|
* Formal Parameters:
|
|
* transport_connection (i)
|
|
* This is the transport connection that is to be broken.
|
|
*
|
|
* Return Value:
|
|
* TRANSPORT_NO_ERROR
|
|
* The operation completed successfully.
|
|
* TRANSPORT_NOT_INITIALIZED
|
|
* The transport stack is not initialized.
|
|
* TRANSPORT_NO_SUCH_CONNECTION
|
|
* This indicates that the specified transport connection does not
|
|
* exist.
|
|
*
|
|
* Side Effects:
|
|
* A transport connection is severed.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* TransportError PollReceiver ()
|
|
*
|
|
* Functional Description:
|
|
* This operation is used to check a transport stack for incoming data (or
|
|
* other events, such as connect and disconnect indications). In a single
|
|
* threaded environment, this call could also be used to provide a
|
|
* time-slice for the processing of inbound data, as well as other events
|
|
* (such as the creation of new connections).
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* TRANSPORT_NO_ERROR
|
|
* The operation completed successfully.
|
|
*
|
|
* Side Effects:
|
|
* This can result in callbacks from the transport layer back into this
|
|
* object.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
#endif
|