/******************************************************************************* ** ** Cabletron Systems Incorporated ** Post Office Box 5005 ** Rochester, NH 03866-5005 ** (c) Copyright Cabletron Systems Inc. 1999 ** ** Workfile: %M% ** Logfile: %P% ** Original Author: Todd Crowley ** SCCS Delta ID: %I% ** Last Delta Date/Time: %G% %U% ** *******************************************************************************/ /******************************************************************************/ /* */ /* File: LfapFlowMgr.h */ /* */ /* This file is the only file the CCE should need to include. All of the */ /* functions that need to be called on the LFAP API from the CCE are */ /* declared in this file. The comments before the functions describe them */ /* in detail. The functions are defined in the LfapFlowMgr.c file. */ /* */ /******************************************************************************/ #ifndef LFAPFLOWMGR_H_ #define LFAPFLOWMGR_H_ #include "LfapStruct.h" #ifdef __cplusplus extern "C" { #endif /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* initializeLfapFlowInfo - initializes a LFAPFlowInfo structure */ /* */ /* SYNOPSIS */ /* */ /* void initializeLfapFlowInfo (LFAPFlowInfo* flow_info) */ /* */ /* flow_info - pointer to a LFAPFlowInfo structure (see LfapStruct.h */ /* for a description). */ /* */ /* DESCRIPTION */ /* */ /* This function initializes all of the members of the LFAPFlowInfo */ /* structure to 0. This function is useful to the CCE because the CCE */ /* uses the LFAPFlowInfo structure when calling LFAP API's LFAPAdmitFlow */ /* function. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ void initializeLfapFlowInfo (LFAPFlowInfo* flow_info); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPInit - initializes the LFAP API */ /* */ /* SYNOPSIS */ /* */ /* void LFAPInit (lfapui16_t stats_type, */ /* lfapui32_t poll_interval, */ /* lfapui16_t batch_size, */ /* lfapui32_t batch_interval, */ /* lfapui32_t lost_conn_interval, */ /* lfapui32_t server_retry_interval, */ /* lfapui32_t max_send_queue_size, */ /* lfapui32_t* server_list, */ /* lfapui16_t server_list_len) */ /* */ /* stats_type - integer indicating what type of statistics the CCE */ /* maintains for flows (LFAP_DELTA_STATS for delta, */ /* LFAP_TOTAL_STATS for total). The default is delta */ /* statistics. */ /* */ /* poll_interval - lfapui32_t time value which indicates how */ /* often statistics for flows are reported to the */ /* server. The default poll interval is 24 hours. */ /* */ /* batch_size - lfapui16_t indicating the number of flow update */ /* notifications that are sent in a single FUN message. */ /* The default batch size is 32 updates (or requests) */ /* in one message. */ /* */ /* batch_interval - lfapui32_t time value which indicates how */ /* long (in milliseconds) to wait before sending */ /* the batched FAR and FUN-Inactive messages. */ /* A group of messages is sent up to the server */ /* if the number of messages grouped is equal to */ /* the batch size, or if this timer expires. The */ /* default is 1 second. */ /* */ /* lost_conn_interval - lfapui32_t time value which indicates how */ /* long the API waits (in milliseconds) for a */ /* response from the server after sending it a */ /* query. If a response is not heard in a */ /* minimum of this time value, the LFAP API */ /* assumes the connection to the server is */ /* lost. The default is 10 seconds. */ /* */ /* server_retry_interval - lfapui32_t time value which indicates */ /* how long to wait (in milliseconds) */ /* before going through the list of servers */ /* trying to connect to one of them. The */ /* default is 1 minute. */ /* */ /* max_send_queue_size - lfapui32_t value which indicates the */ /* maximum number of messages that will be */ /* stored in the send queue before messages */ /* are dropped. The default is 10,000 */ /* messages. */ /* */ /* server_list - array of server IP addresses (in lfapui32_t */ /* form) that the CCE can connect to. */ /* */ /* server_list_len - integer indicating the length of the server */ /* list array (number of entries). */ /* */ /* DESCRIPTION */ /* */ /* This function must be called by the CCE to initialize the LFAP API. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* This function must be called before LFAPProcessWork is called. */ /* */ /******************************************************************************/ void LFAPInit (lfapui16_t stats_type, lfapui32_t poll_interval, lfapui16_t batch_size, lfapui32_t batch_interval, lfapui32_t lost_conn_interval, lfapui32_t server_retry_interval, lfapui32_t max_send_queue_size, lfapui32_t* server_list, lfapui16_t server_list_len); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPUpdateParameters - change any of the tunable parameters */ /* */ /* SYNOPSIS */ /* */ /* void LFAPUpdateParameters (lfapui16_t stats_type, */ /* lfapui32_t poll_interval, */ /* lfapui16_t batch_size, */ /* lfapui32_t batch_interval, */ /* lfapui32_t lost_conn_interval, */ /* lfapui32_t server_retry_interval, */ /* lfapui32_t max_send_queue_size, */ /* lfapui32_t* server_list, */ /* lfapui16_t server_list_len) */ /* */ /* stats_type - integer indicating what type of statistics the CCE */ /* maintains for flows (LFAP_DELTA_STATS for delta, */ /* LFAP_TOTAL_STATS for total). */ /* */ /* poll_interval - lfapui32_t time value which indicates how */ /* often statistics for flows are reported to the */ /* server. The default poll interval is 24 hours. */ /* */ /* batch_size - integer indicating the number of flow update */ /* notifications that are sent in a single FUN message. */ /* */ /* batch_interval - lfapui32_t time value which indicates how */ /* long (in milliseconds) to wait before sending */ /* the batched FAR and FUN-Inactive messages. */ /* A group of messages is sent up to the server */ /* if the number of messages grouped is equal to */ /* the batch size, or if this timer expires. The */ /* default is 1 second. */ /* */ /* lost_conn_interval - lfapui13_t time value which indicates how */ /* long the API waits (in milliseconds) for a */ /* response from the server after sending it a */ /* query. If a response is not heard in a */ /* minimum of this time value, the LFAP API */ /* assumes the connection to the server is */ /* lost. The default is 10 seconds. */ /* */ /* server_retry_interval - lfapui32_t time value which indicates */ /* how long to wait (in milliseconds) */ /* before going through the list of servers */ /* trying to connect to one of them. The */ /* default is 1 minute. */ /* */ /* max_send_queue_size - lfapui32_t value which indicates the */ /* maximum number of messages that will be */ /* stored in the send queue before messages */ /* are dropped. The default is 10,000 */ /* messages. */ /* */ /* server_list - array of server IP addresses (in lfapui32_t */ /* form) that the CCE can connect to. */ /* */ /* server_list_len - integer indicating the length of the server */ /* list array (number of entries). */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to change any of the original */ /* parameters that were specified with the call to the LFAPInit function. */ /* If the CCE calls this function but does not specify a parameter (e.g. */ /* one or more of the parameters is LFAP_DEFAULT) then the parameter will */ /* be set to its default value (excluding the server_list and the */ /* server_list_len, these will stay their original value if LFAP_DEFAULT */ /* is passed in for either). */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ void LFAPUpdateParameters (lfapui16_t stats_type, lfapui32_t poll_interval, lfapui16_t batch_size, lfapui32_t batch_interval, lfapui32_t lost_conn_interval, lfapui32_t server_retry_interval, lfapui32_t max_send_queue_size, lfapui32_t* server_list, lfapui16_t server_list_len); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPTerminate - shut down the LFAP API */ /* */ /* SYNOPSIS */ /* */ /* void LFAPTerminate (void) */ /* */ /* DESCRIPTION */ /* */ /* This function shuts down the LFAP API. The LFAP API cleans up its */ /* memory, and disconnects from the server (by calling the CCE */ /* LFAPDisconnect function). */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* After this function is called, the CCE should not return any timer */ /* callbacks, nor should it call LFAPProcessWork, LFAPReceiveMessage, or */ /* LFAPConnectionLost. */ /* */ /******************************************************************************/ void LFAPTerminate (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPProcessWork - main work loop for the LFAP API */ /* */ /* SYNOPSIS */ /* */ /* lfapui16_t LFAPProcessWork (void) */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to allow the LFAP API to do work. */ /* Every major operation is completed in this function, in an incremental */ /* fashion. This function will not always complete all of the work the */ /* LFAP API has to do, it will do an appropriate amount of work before */ /* returning. The work that is completed in this function is as follows: */ /* */ /* - processing timers */ /* - sending messages */ /* - receiving messages */ /* - flow updates */ /* - connecting to a server */ /* - failing over to a new server */ /* */ /* RETURN */ /* */ /* Unsigned int that indicates if more work needs to be done. If there is */ /* more work to be completed, LFAP_WORK_INCOMPLETE is returned, otherwise */ /* LFAP_WORK_COMPLETED is returned. */ /* */ /* CAVEATS */ /* */ /* Must be called continually, even if LFAP_WORK_COMPLETED is returned. */ /* This function should be called in an infinite loop, as long as the */ /* LFAP API has been initialized (with a call to LFAPInit). This function */ /* should be called up until LFAPTerminate is called to shut down the LFAP */ /* API. */ /* */ /******************************************************************************/ lfapui16_t LFAPProcessWork (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPGetFlowId - request for a new unique Flow ID */ /* */ /* SYNOPSIS */ /* */ /* lfapui32_t LFAPGetFlowId (void) */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to request that the LFAP API provide */ /* a Flow ID to be used for a recognized flow. A return value of 0 */ /* indicates that no server is available (invalid Flow ID). */ /* */ /* RETURN */ /* */ /* Unsigned long unique Flow ID. */ /* */ /* CAVEATS */ /* */ /* Must be called before LFAPAdmitFlow is called. */ /* */ /******************************************************************************/ lfapui32_t LFAPGetFlowId (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPAdmitFlow - tell the server about a new flow */ /* */ /* SYNOPSIS */ /* */ /* void LFAPAdmitFlow (lfapui32_t flow_id, LFAPFlowInfo* flow_info) */ /* */ /* flow_id - lfapui32_t unique identifier that was obtained by */ /* calling the LFAPGetFlowId function. */ /* */ /* flow_info - pointer to a LFAPFlowInfo structure that contains all */ /* of the relevant information for the definition of the */ /* flow (see LfapStruct.h file for a description). */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to request that the LFAP API */ /* initiate a Flow Admission Request (FAR) to the server. The flow_id */ /* must be a unique identifier having been obtained by calling the */ /* LFAPGetFlowId function prior to calling this function. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* LFAPGetFlowId must be called and have returned a valid Flow ID (not 0) */ /* before this function is called. */ /* */ /******************************************************************************/ void LFAPAdmitFlow (lfapui32_t flow_id, LFAPFlowInfo* flow_info); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPFlowDeleted - indicate to the LFAP API the flow has been removed */ /* */ /* SYNOPSIS */ /* */ /* void LFAPFlowDeleted (lfapui32_t flow_id, LFAPFlowStats* flow_stats) */ /* */ /* flow_id - lfapui32_t unique identifier for the flow. */ /* */ /* flow_stats - pointer to a LFAPFlowStats structure (see */ /* LfapStruct.h for a description). flow_stats */ /* contains the final statistics for the flow, if */ /* available. */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to indicate to the LFAP API that the */ /* connection has been removed and the flow is to be removed. It is */ /* called by the CCE when it removes the flow. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ void LFAPFlowDeleted (lfapui32_t flow_id, LFAPFlowStats* flow_stats); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPConnectionLost - indicate to the LFAP API the connection to the */ /* server has been lost */ /* */ /* SYNOPSIS */ /* */ /* void LFAPConnectionLost (lfapui32_t server_ip) */ /* */ /* server_ip - lfapui32_t form of the IP address of the server */ /* with whom connection was lost. */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to indicate to the LFAP API that the */ /* connection to the server has been lost. This function will return */ /* immediately, but the LFAP API now knows it has lost connection to the */ /* server. The LFAPProcessWork function will do the work of trying to */ /* connect to a server. The LFAP API will immediately try to reconnect to */ /* the next server in it's list of servers (calling the CCE LFAPConnect */ /* function). The LFAP API will continually try to connect to a server */ /* (rotating through the list of servers) until the list has been gone */ /* through once completely. If none of the servers in the server list can */ /* be contacted, then a retry timer is set. Once the timer expires, each */ /* of the servers in the list are attempted to be contacted again. If */ /* this also fails, then another timer is set, and the retry process */ /* begins again. */ /* */ /* If the CCE wishes to not contact any server, then the CCE can call the */ /* LFAP API LFAPTerminate function, and not return the timer that was set. */ /* LFAP will then be completely disabled. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ void LFAPConnectionLost (lfapui32_t server_ip); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPReceiveMessage - give LFAP message received from the server to the */ /* LFAP API for processing */ /* */ /* SYNOPSIS */ /* */ /* void LFAPReceiveMessage (void* buf, int buf_len) */ /* */ /* buf - pointer to a complete LFAP message (including the header). */ /* */ /* buf_len - length of the complete LFAP message (including the */ /* length of the header). */ /* */ /* DESCRIPTION */ /* */ /* This function is called by the CCE to give the LFAP API the LFAP */ /* message received from the server. The client communication software in */ /* the CCE needs to do very little when a message is received before */ /* calling this function. When a message is received, the client */ /* communication software has to read at least LFAP_HEADER_SIZE bytes of */ /* the message so that the header is read. The LFAPDecodeMsgLen function */ /* is called with a pointer to the buffer read as the parameter. The */ /* length of the message body (does not include the length of the LFAP */ /* message header) in bytes is returned by the function. The LFAP message */ /* must be read (now that the length is known) and a pointer to the */ /* complete message (which includes the header) is passed to this function */ /* along with the length of the complete LFAP message (includes the length */ /* of the header). The message is not processed in this function. */ /* */ /* RETURN */ /* */ /* Nothing. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ void LFAPReceiveMessage (void* buf, int buf_len); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPDecodeMsgLen - decodes the length field of the LFAP message header */ /* */ /* SYNOPSIS */ /* */ /* int LFAPDecodeMsgLen (void* buf) */ /* */ /* buf - pointer to a the beginning of an LFAP message fragment that */ /* is at least LFAP_HEADER_SIZE bytes in length. */ /* */ /* DESCRIPTION */ /* */ /* This function decodes the length field of an LFAP message header. This */ /* enables an incoming TCP/IP stream to be divided into individual LFAP */ /* messages for processing. */ /* */ /* RETURN */ /* */ /* Integer specifying the length of the message body in bytes. This does */ /* not include the length of the LFAP message header (which is */ /* LFAP_HEADER_SIZE bytes). */ /* */ /* CAVEATS */ /* */ /* No error checking is completed in this function. */ /* */ /******************************************************************************/ int LFAPDecodeMsgLen (void* buf); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPGetLastError - returns the last error that occurred in the LFAP API */ /* */ /* SYNOPSIS */ /* */ /* const LFAPError* LFAPGetLastError (void) */ /* */ /* DESCRIPTION */ /* */ /* This function returns a const pointer to a LFAPError structure (see */ /* LfapStruct.h for a description) which indicates the most recent error */ /* that has occurred and the time it occurred in the LFAP API. If no */ /* error has occurred, then the error value is LFAP_NO_ERROR_OCCURRED, and */ /* the time is 0. When an error occurs, the time is set by calling the */ /* CCE LFAPGetUptime function. The possible error values are the */ /* following: */ /* LFAP_NO_ERROR_OCCURRED, */ /* LFAP_NO_SERVERS_IN_LIST, */ /* LFAP_NO_SERVERS_AVAILABLE, */ /* LFAP_INCOMPATIBLE_VERSION, */ /* LFAP_RCVD_PARTIAL_MESSAGE, */ /* LFAP_INVALID_FLOW_PREFIX_RCVD. */ /* See LfapStruct.h for a brief description of each. */ /* */ /* RETURN */ /* */ /* Const pointer to a LFAPError structure which indicates the last error */ /* that occurred in the LFAP API, and the time it occurred. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ const LFAPError* LFAPGetLastError (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPGetApiStats - get current LFAP API statistics */ /* */ /* SYNOPSIS */ /* */ /* const LfapApiStats* LFAPGetApiStats (void) */ /* */ /* DESCRIPTION */ /* */ /* This function returns a const pointer to a LfapApiStats structure (see */ /* LfapStruct.h for a description) which has the most recent statistics */ /* of the LFAP API. */ /* */ /* RETURN */ /* */ /* Const pointer to a LfapApiStats structure which has the most recent */ /* statistics of the LFAP API. */ /* */ /* CAVEATS */ /* */ /* If the LFAP API has not been initialized yet (LFAPInit has not been */ /* called) or if the LFAP API has been terminated (LFAPTerminate has been */ /* called), then this function will return 0. */ /* */ /******************************************************************************/ const LFAPApiStats* LFAPGetApiStats (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPGetActiveServer - get current server CCE is connected to */ /* */ /* SYNOPSIS */ /* */ /* lfapui32_t LFAPGetActiveServer (void) */ /* */ /* DESCRIPTION */ /* */ /* This function returns the lfapui32_t format of the IP address of the */ /* server that the CCE is connected to. If the CCE is not connected to a */ /* server, 0 is returned. */ /* */ /* RETURN */ /* */ /* Unsigned long form of the IP address of the server. */ /* */ /* CAVEATS */ /* */ /* If the CCE is not connected to a server, 0 is returned. */ /* */ /******************************************************************************/ lfapui32_t LFAPGetActiveServer (void); /******************************************************************************/ /* */ /* FUNCTION */ /* */ /* LFAPGetConnectionStatus - get current connection status */ /* */ /* SYNOPSIS */ /* */ /* int LFAPGetConnectionStatus (void) */ /* */ /* DESCRIPTION */ /* */ /* This function returns an integer that indicates the current status of */ /* the connection to a server. The status is one of the following: */ /* */ /* LFAP_ALREADY_TRYING_TO_CONNECT - trying to connect */ /* LFAP_TCP_CONNECTED_NO_ACK - tcp connected, no ack from server */ /* LFAP_CONNECTION_ESTABLISHED - connected, ack received */ /* LFAP_CONNECTION_LOST - lost connection */ /* LFAP_TCP_CONNECTION_FAILED - could not connect to a server */ /* */ /* RETURN */ /* */ /* int indicating status of the connection. */ /* */ /* CAVEATS */ /* */ /* None. */ /* */ /******************************************************************************/ LFAPConnState_t LFAPGetConnectionStatus (void); #ifdef __cplusplus } #endif #endif /* LFAPFLOWMGR_H_ */