tfLqmRegisterMonitor

Table of Contents >> Optional Protocols >> PPP Interface

#include <trsocket.h>

int tfLqmRegisterMonitor	(
	ttUserInterface interfaceHandle,
	ttLqmMonitorFuncPtr monitorFuncPtr,
	ttUser16Bit hysteresisMaxFailures,
	ttUser16Bit hysteresisSamples
	);

Function Description

This function enables the user to specify a policy for determining link quality, specifically by registering a user-defined link quality monitoring function. tfLqmRegisterMonitor() should be called after the call to tfUsePppLqm() for each distinct PPP interface that the user wants to monitor link quality on. It is highly recommended that you use a LQR timer to pace the sending of LQRs, otherwise if the link is very bad incoming, your link quality monitoring function won't be called frequently enough to allow you recover the link in a timely fashion, since without a LQR timer it is only called when a LQR is received.

The user-defined link quality monitoring function (specified by monitorFuncPtr) must return 0 if link quality is good, and a weighted non-zero value if link quality is bad (i.e. a value of 2 is twice as bad as a value of 1, etc.). When the accumulated value of bad counts returned by your link quality monitoring function exceeds 'hysteresisMaxFailures' within the last 'hysteresisSamples' times of calling your function, you will be notified via the PPP callback flag TM_LL_LQM_LINK_BAD (if you registered a link notification function, refer to tfUseAsyncPpp()) that the link is bad so that you can attempt recovery. The link quality monitoring function will be called when one of the following events happens:

1. A timeout occurs while waiting to receive a solicited Link-Quality-Report message from the peer. The peer negotiated for us to use a non-zero LQM reporting period, which means that we are using the LQR timer to pace our sending of Link-Quality-Report messages. This timer expired, and we haven't yet received a Link-Quality-Report message from the peer for a Link-Quality-Report message we sent earlier (i.e. 'reasonCode' set to TM_LQM_MONITOR_TIMEOUT).
2. A Link-Quality-Report message is received from the peer (i.e. 'reasonCode' set to TM_LQM_MONITOR_LQR).

Note:

The peer may not support LQM, in which case the link quality monitoring function will never be called indicating that LQM is not being used on the link.

The function prototype for the link quality monitoring function (specified by monitorFuncPtr) is defined as follows:

ttUser8Bit myLinkQualityMonitor	(
	ttUserInterface interfaceHandle,
	int reasonCode,
	unsigned long timeElapsedMsec,
	ttLqrCountDeltasPtr countDeltasPtr,
	ttConstLqrCountsPtr countsPtr,
	ttUser32Bit outLqrs,
	ttUser32Bit outPackets,
	ttUser32Bit outOctets
	);

• 'reasonCode' can take on the values TM_LQM_MONITOR_LQR or TM_LQM_MONITOR_TIMEOUT, depending on whether the reason for the callback is that a Link-Quality-Report message was received (TM_LQM_MONITOR_LQR), or that the timeout occurred before the solicited/expected Link-Quality-Report message was received (TM_LQM_MONITOR_TIMEOUT).

• 'timeElapsedMsec' is the time elapsed (in milliseconds) since the last time the link quality monitoring function was called

• 'outLqrs' is the count of LQRs sent

• 'outPackets' is the count of packets sent

• 'outOctets' is the count of bytes sent.

Note:

Since 'outLqrs', 'outPackets', and 'outOctets' are unsigned 32-bit counters, they may wrap around to 0.

When 'reasonCode' is set to TM_LQM_MONITOR_LQR:

1. 'countDeltasPtr' points to the absolute counts of packets and bytes sent and received (as reported by the peer in the received Link-Quality-Report message) since the last time the link quality monitoring function was called.
2. 'countsPtr' points to the relative counts of packets and bytes sent and received (as reported by the peer in the received Link-Quality-Report message). You must not change any of these counts, since they are used internally.
3. 'countsPtr->lastOutLQRs' may be compared with 'countsPtr->peerInLQRs' to determine how many outbound LQRs have been lost.
4. 'countsPtr->lastOutLQRs' may be compared with 'outLQRs' to determine how many outbound LQRs are still in the pipeline.
5. 'countDeltasPtr->deltaPeerInPackets' may be compared with 'countDeltasPtr->deltaLastOutPackets' to determine the number of lost packets over the outgoing link.
6. 'countDeltasPtr->deltaPeerInOctets' may be compared with 'countDeltasPtr->deltaLastOutOctets' to determine the number of lost octets over the outgoing link.
7. 'countDeltasPtr->deltaSaveInPackets' may be compared with 'countDeltasPtr->deltaPeerOutPackets' to determine the number of lost packets over the incoming link.
8. 'countDeltasPtr->deltaSaveInOctets' may be compared with 'countDeltasPtr->deltaPeerOutOctets' to determine the number of lost octets over the incoming link.
9. 'countDeltasPtr->deltaPeerInDiscards' and 'countDeltasPtr->deltaPeerInErrors' may be used to determine whether packet loss is due to congestion in the peer rather than physical link failure.

When 'reasonCode' is set to TM_LQM_MONITOR_TIMEOUT, 'countDeltasPtr' and 'countsPtr' are NULL.

If link quality is good, your link quality monitoring function should return 0, otherwise it should return 1, unless you want to reduce the hysteresis and speed up the process of link failure in which case it should return a value greater than 1.

Note:

Your link quality monitoring function is called with the device locked. You cannot call any LQM public API functions from the monitoring function (doing so will result in deadlock, if you have defined the macro TM_LOCK_NEEDED to enable locking).

For example, if your monitoring function determines that the link is good outgoing but very bad incoming, and you want to send LQRs at a faster rate in this case (per RFC 1989), you cannot call tfLqmSendLinkQualityReport() or tfLqmSetLqrTimerPeriod() directly from your monitoring function since doing so will result in deadlock. Instead, have your monitoring function set a flag, which you can then poll in another task (or in your main polling loop) that can then call the appropriate LQM public API functions.

Parameters

• interfaceHandle

  The PPP interface to use this link quality monitoring routine with.

• monitorFuncPtr

  The function to call to monitor link quality.

• hysteresisMaxFailures

  Set to 0 if we aren't using any hysteresis, otherwise this is the maximum number of bad link quality counts we are allowed to get back from calls to the user's link quality monitoring function within the specified sampling period (i.e. 'hysteresisSamples') before we will notify the user that the link is bad.

• hysteresisSamples

  Set to 0 if we aren't using any hysteresis, otherwise this is the sampling period (specified as the number of calls to the user's link quality monitoring function) used to determine if the link is bad.

Returns

• TM_ENOERROR

  Success.

• TM_EINVAL

  Invalid parameter.

• TM_EOPNOTSUPP

  tfUsePppLqm() has not yet been called.

Table of Contents >> Optional Protocols >> PPP Interface