You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
674 lines
25 KiB
674 lines
25 KiB
/* TransportController.h
|
|
*
|
|
* Copyright (c) 1993-1995 by DataBeam Corporation, Lexington, KY
|
|
*
|
|
* Abstract:
|
|
* This is the Transport Controller file for the MCATPSTN DLL.
|
|
*
|
|
* This DLL instantiates a PSTNController which controls the
|
|
* making and breaking of connections. This routine also constructs and
|
|
* destructs T123 stacks. When the physical layer creates or detects a
|
|
* connection this class is notified. It then instantiates a T123 object
|
|
* which sets up a T123 stack to control this physical connection. The
|
|
* T123 stace notifies this controller when a connection is up and running.
|
|
* It also notifies this controller if the link is broken for some reason.
|
|
* As a result, this controller notifies the user of the new or broken
|
|
* connection.
|
|
*
|
|
* When the user wants to make a data request of a specific transport
|
|
* connection, this controller maps the connection id to a T123 stack. The
|
|
* data request is passed on to that stack. Data Indications are passed
|
|
* to the user by the T123 stack. The controller does not need to know
|
|
* about these and lets the T123 stack handle them.
|
|
*
|
|
* POLLING THE DLL:
|
|
* This stack is maintained by the Poll calls (PollTransmitter() and
|
|
* PollReceiver()). During these calls we transmit and receive
|
|
* packets with the remote sites. It is extremely important that
|
|
* this DLL receive a time slice from the CPU on a regular and
|
|
* frequent basis. This will give us the time we need to properly
|
|
* maintain the link. If these calls are not used in a frequent and
|
|
* regular basis, the communications link will be unproductive and
|
|
* could eventually be lost.
|
|
*
|
|
* USER CALLBACKS:
|
|
* The user communicates with this DLL by making calls directly to the
|
|
* DLL. The DLL communicates with the user by issuing callbacks.
|
|
* The TInitialize() call accepts as a parameter, a callback address and
|
|
* a user defined variable. When a significant event occurs in the DLL,
|
|
* the DLL will jump to the callback address. The first parameter of
|
|
* the callback is the message. This could be a
|
|
* TRANSPORT_CONNECT_INDICATION, TRANSPORT_DISCONNECT_INDICATION, or any
|
|
* number of significant events. The second parameter is a message
|
|
* specific parameter. The third parameter is the user defined variable
|
|
* that was passed in during the TInitialize() function. See the
|
|
* mcattprt.h interface file for a complete description of the callback
|
|
* messages.
|
|
*
|
|
* MAKING A CALL:
|
|
* After the initialization has been done, the user will eventually,
|
|
* want to attempt a connection. The user issues a TConnectRequest() call
|
|
* with the PSTN address of the remote location. The connection request
|
|
* is passed on to the PSTNcontroller. It eventually issues a callback to
|
|
* the this controller to say that the connection was successful and passes
|
|
* up the address of the physical layer. If the physical handle passed up
|
|
* by the PSTNController is a new handle, we create a T123 object, and
|
|
* issue a ConnectRequest() to it. The T123 object creates a T.123
|
|
* compliant stack and notifies the Controller when it is up and running.
|
|
* If the handle passed up from the PSTNController is currently associated
|
|
* with an already active T123 object, we simply make a ConnectRequest()
|
|
* call to the T123 object so that it will create another logical
|
|
* connection over the same physical connection.
|
|
*
|
|
* RECEIVING A CALL:
|
|
* If we receive a call from a remote location, the PSTNController notifies
|
|
* us that a new connection is being attempted. We then create a new
|
|
* T123 stack associated with the physical connection. The T123 stack
|
|
* will notify us if new a Transport Connection id need to be generated.
|
|
* It will also notify us when the Transport Connection is up and running.
|
|
*
|
|
* SENDING PACKETS:
|
|
* To send data to the remote location, use the DataRequest() function
|
|
* call. This controller will pass the packet to the T123 stack that it is
|
|
* associated with. The send may actually occur after the call has
|
|
* returned to the user.
|
|
*
|
|
* RECEIVING PACKETS:
|
|
* The user receives packets by DATA_INDICATION callbacks. When the
|
|
* user makes PollReceiver() calls, the Transport Layer checks its input
|
|
* buffers for packets. If a packet is found, we issue a DATA_INDICATION
|
|
* callback to the user with the Transport Connection handle, the address
|
|
* of the packet, and the packet length.
|
|
*
|
|
* DISCONNECTING A TRANSPORT:
|
|
* To disconnect a transport connection, use the DisconnectRequest()
|
|
* function. After the link has been brought down, we perform a
|
|
* callback to the user to verify the disconnect.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*
|
|
* Author:
|
|
* James W. Lawwill
|
|
*
|
|
*/
|
|
#ifndef _TRANSPORT_CONTROLLER_
|
|
#define _TRANSPORT_CONTROLLER_
|
|
|
|
#include "t123.h"
|
|
|
|
#define TRANSPORT_CONTROLLER_MESSAGE_BASE 0
|
|
|
|
|
|
|
|
/*
|
|
** Each Logical Connection has a LogicalConnectionStruct associated
|
|
** with it.
|
|
**
|
|
** physical_layer - Pointer to physical layer associated with
|
|
** this logical connection.
|
|
** physical_handle - Each physical connection has a
|
|
** physical_handle associated with it.
|
|
** protocol_stack - The T123 object associated with it.
|
|
** priority - Priority of the logical connection
|
|
** t123_connection_requested - TRUE if this logical connection has issued
|
|
** a ConnectRequest() to the t123 object.
|
|
** t123_disconnect_requested - TRUE if this logical connection has issued
|
|
** a DiconnectRequest() to the t123 object.
|
|
*/
|
|
typedef struct
|
|
{
|
|
BOOL fCaller;
|
|
ComPort *comport; // physical layer
|
|
PhysicalHandle hCommLink; // physical handle
|
|
T123 *t123; // protocal stack
|
|
TransportPriority priority;
|
|
BOOL t123_connection_requested;
|
|
BOOL t123_disconnect_requested;
|
|
}
|
|
LogicalConnectionStruct, * PLogicalConnectionStruct;
|
|
|
|
|
|
class TransportController
|
|
{
|
|
public:
|
|
|
|
TransportController(void);
|
|
~TransportController (void);
|
|
|
|
/*
|
|
** Functions related making and breaking a link
|
|
*/
|
|
TransportError CreateTransportStack(
|
|
BOOL fCaller,
|
|
HANDLE hCommLink,
|
|
HANDLE hevtClose,
|
|
PLUGXPRT_PARAMETERS *);
|
|
TransportError CloseTransportStack(
|
|
HANDLE hCommLink);
|
|
TransportError ConnectRequest (
|
|
LogicalHandle *logical_handle,
|
|
HANDLE hCommLink,
|
|
TransportPriority transport_priority = DEFAULT_PRIORITY);
|
|
TransportError ConnectResponse (
|
|
LogicalHandle logical_handle);
|
|
TransportError DisconnectRequest (
|
|
LogicalHandle logical_handle,
|
|
UINT_PTR trash_packet);
|
|
|
|
/*
|
|
** This function is used to send a data packet
|
|
*/
|
|
TransportError DataRequest (
|
|
LogicalHandle logical_handle,
|
|
LPBYTE user_data,
|
|
ULONG user_data_length);
|
|
TransportError PurgeRequest (
|
|
LogicalHandle logical_handle);
|
|
void EnableReceiver (void);
|
|
|
|
/*
|
|
** These four functions are the heartbeat of the DLL. Transmission
|
|
** and reception of data occur during these calls.
|
|
*/
|
|
void PollReceiver(void);
|
|
void PollReceiver(PhysicalHandle);
|
|
void PollTransmitter(void);
|
|
void PollTransmitter(PhysicalHandle);
|
|
|
|
/*
|
|
** Miscellaneous utilities
|
|
*/
|
|
TransportError ProcessCommand (
|
|
USHORT message,
|
|
PVoid input_structure,
|
|
PVoid output_structure);
|
|
|
|
/*
|
|
** Callback used by the PSTNController and the T123 objects
|
|
*/
|
|
ULONG_PTR OwnerCallback(ULONG, void *p1 = NULL, void *p2 = NULL, void *p3 = NULL);
|
|
|
|
PhysicalHandle GetPhysicalHandle (
|
|
LogicalHandle logical_handle);
|
|
|
|
private:
|
|
|
|
LogicalHandle GetNextLogicalHandle (void);
|
|
void ProcessMessages (void);
|
|
void RemoveLogicalConnections (
|
|
PhysicalHandle physical_handle);
|
|
void Reset (
|
|
BOOL notify_user);
|
|
TransportError NewConnection (
|
|
PhysicalHandle physical_handle,
|
|
BOOL link_originator,
|
|
ComPort *physical_layer);
|
|
TransportError CreateT123Stack(
|
|
PhysicalHandle hCommLink,
|
|
BOOL link_originator, // fCaller
|
|
ComPort *comport,
|
|
PLUGXPRT_PARAMETERS *pParams);
|
|
|
|
private:
|
|
|
|
/*
|
|
** This is a list of the physical connections we currently have.
|
|
** It is associated with a structure that holds each layer in
|
|
** the stack(s).
|
|
*/
|
|
DictionaryClass Protocol_Stacks; // list of T123 objects
|
|
DictionaryClass Logical_Connection_List;
|
|
SListClass Transmitter_List;
|
|
SListClass Message_List;
|
|
|
|
BOOL Emergency_Shutdown;
|
|
BOOL Poll_Active;
|
|
};
|
|
|
|
#endif
|
|
|
|
|
|
/*
|
|
* Documentation for Public class members
|
|
*/
|
|
|
|
/*
|
|
* TransportController::TransportController (
|
|
* PTransportResources transport_resources);
|
|
*
|
|
* Functional Description
|
|
* This is the Transport Controller constructor. This routine instantiates
|
|
* a PSTNController() and routes calls to the proper location.
|
|
*
|
|
* Formal Parameters
|
|
* transport_resources - (i) This is the address TransportResources
|
|
* structure.
|
|
*
|
|
* Return Value
|
|
* None
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportController::~TransportController (void)
|
|
*
|
|
* Functional Description
|
|
* This is the TransportController destructor. It deletes the
|
|
* PSTNController and any T123 objects that are alive.
|
|
*
|
|
* Formal Parameters
|
|
* None
|
|
*
|
|
* Return Value
|
|
* None
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::ConnectRequest (
|
|
* TransportAddress transport_address,
|
|
* TransportPriority transport_priority,
|
|
* LogicalHandle *logical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function initiates a connection. It calls the PSTNController with
|
|
* the transport_address so that it can start the connection procedure.
|
|
* When this routine returns, it does NOT mean that a connection exists.
|
|
* It means that a connection is in progress and will eventually be
|
|
* completed when the user receives a TRANSPORT_CONNECT_CONFIRM or
|
|
* TRANSPORT_DISCONNECT_INDICATION.
|
|
*
|
|
* Formal Parameters
|
|
* transport_address - (i) Address of ascii string containing the
|
|
* telephone number or physical handle.
|
|
* transport_priority - (i) Requested priority of the connection.
|
|
* This value can be 0-14 inclusive.
|
|
* logical_handle - (o) Address of transport connection. We return
|
|
* a unique transport connection number as the
|
|
* result of a successful dial operation.
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
* TRANSPORT_NO_CONNECTION_AVAILABLE - No resources for the connection
|
|
* TRANSPORT_CONNECT_REQUEST_FAILED - Unable to reach the address
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::ConnectResponse (
|
|
* LogicalHandle logical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function is called in response to a TRANSPORT_CONNECT_INDICATION
|
|
* callback. The user should call this function or the
|
|
* DisconnectRequest() function if that don't want the logical connection.
|
|
*
|
|
* Formal Parameters
|
|
* logical_handle - (i) Logical handle that we are responding to.
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
* TRANSPORT_NO_SUCH_CONNECTION - Transport connection does not exist
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::DisconnectRequest (
|
|
* LogicalHandle logical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function terminates the user's transport connection. The user
|
|
* will receive a DISCONNECT_INDICATION when the connection is broken.
|
|
* If we are multiplexing multiple connections over the same physical
|
|
* connection, we will not break the physical comm. link until the last
|
|
* connection is broken.
|
|
*
|
|
* Formal Parameters
|
|
* logical_handle - (i) Transport connection number to terminate
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
* TRANSPORT_NO_SUCH_CONNECTION - Transport connection does not exist
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::DataRequest (
|
|
* LogicalHandle logical_handle,
|
|
* LPBYTE user_data,
|
|
* ULONG user_data_length);
|
|
*
|
|
* Functional Description
|
|
* This function is used to send a data packet to the remote location.
|
|
*
|
|
* Formal Parameters
|
|
* logical_handle - (i) Transport connection number
|
|
* user_data - (i) Address of data to send
|
|
* user_data_length - (i) Length of data to send
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
* TRANSPORT_NO_SUCH_CONNECTION - Transport connection does not exist
|
|
* TRANSPORT_PACKET_TOO_LARGE - Packet is bigger than acceptable
|
|
* size
|
|
* TRANSPORT_WRITE_QUEUE_FULL - Transport write queues are already
|
|
* full.
|
|
* TRANSPORT_NOT_READY_TO_TRANSMIT - The transport layer is in the
|
|
* process of building or breaking
|
|
* down the transport stack and is
|
|
* not ready for user data.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* The maximum size of a packet is 8192 bytes.
|
|
*/
|
|
|
|
/*
|
|
* void TransportController::EnableReceiver (void);
|
|
*
|
|
* Functional Description
|
|
* This function is called by the user application to notify us that
|
|
* it is ready for more data. We only receive this call if we had
|
|
* previously attempted a TRANSPORT_DATA_INDICATION and it was rejected.
|
|
*
|
|
* Formal Parameters
|
|
* None.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::PurgeRequest (
|
|
* LogicalHandle logical_handle)
|
|
*
|
|
* Functional Description
|
|
* This function is used purge outbound packets
|
|
*
|
|
* Formal Parameters
|
|
* logical_handle - (i) Transport connection number
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
* TRANSPORT_NO_SUCH_CONNECTION - Transport connection does not exist
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* void TransportController::PollReceiver (void);
|
|
*
|
|
* Functional Description
|
|
* This function gives the DLL a chance to take the data received and
|
|
* pass it to the user.
|
|
*
|
|
* Formal Parameters
|
|
* None.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* void TransportController::PollReceiver (
|
|
* PhysicalHandle physical_handle)
|
|
*
|
|
* Functional Description
|
|
* This function calls the T123 stack associated with the physical
|
|
* handle.
|
|
*
|
|
* Formal Parameters
|
|
* physical_handle (i) - Handle of the T123 stack that we need
|
|
* to maintain.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* void TransportController::PollTransmitter (void);
|
|
*
|
|
* Functional Description
|
|
* This function processes output data to remote locations.
|
|
*
|
|
* Formal Parameters
|
|
* None.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* void TransportController::PollTransmitter (
|
|
* PhysicalHandle physical_handle)
|
|
*
|
|
* Functional Description
|
|
* This function calls the T123 stack associated with the physical
|
|
* handle.
|
|
*
|
|
* Formal Parameters
|
|
* physical_handle (i) - Handle of the T123 stack that we need
|
|
* to maintain.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TransportError TransportController::ProcessCommand (
|
|
* USHORT message,
|
|
* PVoid input_structure,
|
|
* PVoid output_structure)
|
|
*
|
|
* Functional Description
|
|
* This function passes in a command and command-specific parameters.
|
|
*
|
|
* Formal Parameters
|
|
* message - (i) Message to execute
|
|
* input_structure - (i) Pointer to data type related to message
|
|
* output_structure - (o) Pointer to data type related to message
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TPhysicalError TransportController::PhysicalConnectRequest (
|
|
* ULONG connect_type,
|
|
* PVoid connect_parameter,
|
|
* PVoid physical_configuration,
|
|
* PPhysicalHandle physical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function initiates a physical connection.
|
|
*
|
|
* Formal Parameters
|
|
* connect_type - (i) Type of connection to make
|
|
* connect_parameter - (i) Pointer to parameter associated with
|
|
* connect_type.
|
|
* physical_configuration - (i) Pointer to configuration structure.
|
|
* physical_handle - (o) Pointer to PhysicalHandle.
|
|
*
|
|
* Return Value
|
|
* TPHYSICAL_NO_ERROR - No error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TPhysicalError TransportController::PhysicalListen (
|
|
* ULONG listen_type,
|
|
* PVoid listen_parameter,
|
|
* PVoid physical_configuration,
|
|
* PPhysicalHandle physical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function initiates a physical connection listen.
|
|
*
|
|
* Formal Parameters
|
|
* listen_type - (i) Type of connection to make
|
|
* listen_parameter - (i) Pointer to parameter associated with
|
|
* listen_type.
|
|
* physical_configuration - (i) Pointer to configuration structure.
|
|
* physical_handle - (o) Pointer to PhysicalHandle.
|
|
*
|
|
* Return Value
|
|
* TPHYSICAL_NO_ERROR - No error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TPhysicalError TransportController::PhysicalUnlisten (
|
|
* PhysicalHandle physical_handle);
|
|
*
|
|
* Functional Description
|
|
* This function takes a physical connection out of the listen mode.
|
|
*
|
|
* Formal Parameters
|
|
* physical_handle - (i) physical handle
|
|
*
|
|
* Return Value
|
|
* TPHYSICAL_NO_ERROR - No error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* TPhysicalError TransportController::PhysicalDisconnectRequest (
|
|
* PhysicalHandle physical_handle,
|
|
* PhysicalDisconnectMode disconnect_mode);
|
|
*
|
|
* Functional Description
|
|
* This function disconnects a physical connection. Depending on the
|
|
* disconnect_mode, the port may be released to the user. If the
|
|
* mode is TPHYSICAL_NOWAIT, the port is released when the function
|
|
* returns. Otherwise, it is released when the
|
|
* TPHYSICAL_DISCONNECT_CONFIRM callback is issued.
|
|
*
|
|
* Formal Parameters
|
|
* physical_handle - (i) physical handle
|
|
* disconnect_mode - (i) TPHYSICAL_WAIT, if you want to shutdown cleanly.
|
|
* TPHYSICAL_NOWAIT, if you want to do a hard
|
|
* shutdown of the physical connection.
|
|
*
|
|
* Return Value
|
|
* TPHYSICAL_NO_ERROR - No error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|
|
/*
|
|
* ULONG TransportController::OwnerCallback (
|
|
* USHORT layer_message,
|
|
* ULONG parameter1,
|
|
* ULONG parameter2,
|
|
* PVoid parameter3);
|
|
*
|
|
* Functional Description
|
|
* This is the owner callback function. This function is called by
|
|
* objects that are owned by the TransportController. This is basically
|
|
* their way of communicating with the TransportController. When the
|
|
* controller calls an object (i.e. PSTNController or a T123 object), it
|
|
* can call the owner back with message it wants processed. This is a
|
|
* little tricky but it works well.
|
|
*
|
|
* Formal Parameters
|
|
* command_string - (i) String containing the operation to perform. It
|
|
* also contains any parameters that are necessary
|
|
* for the function.
|
|
* parameter1 - (i) Message specific parameter
|
|
* parameter2 - (i) Message specific parameter
|
|
* parameter3 - (i) Message specific parameter
|
|
*
|
|
* Return Value
|
|
* TRANSPORT_NO_ERROR - No Error
|
|
*
|
|
* Side Effects
|
|
* None
|
|
*
|
|
* Caveats
|
|
* None
|
|
*/
|
|
|