|
|
/* 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 */
|
