Common Fibre Channel HBA Information Library Functions
HBA_RegisterForAdapterEvents(3HBAAPI)
NAME
HBA_RegisterForAdapterEvents,
HBA_RegisterForAdapterAddEvents,
HBA_RegisterForAdapterPortEvents,
HBA_RegisterForAdapterPortStatEvents,
HBA_RegisterForTargetEvents, HBA_RegisterForLinkEvents,
HBA_RemoveCallback - SNIA event handling functions
SYNOPSIS
cc [ flag... ] file... -lHBAAPI [ library... ]
#include
HBA_STATUS HBA_RegisterForAdapterEvents(void (*pCallback)
(void *pData, HBA_WWN PortWWN, HBA_UINT32 eventType),
void *pUserData, HBA_HANDLE handle,
HBA_CALLBACKHANDLE *pCallbackHandle);
HBA_STATUS HBA_RegisterForAdapterAddEvents(void (*pCallback)
(void *pData, HBA_WWN PortWWN, HBA_UINT32 eventType),
void *pUserData, HBA_CALLBACKHANDLE *pCallbackHandle);
HBA_STATUS HBA_RegisterForAdapterPortEvents(void (*pCallback)
(void *pData, HBA_WWN PortWWN, HBA_UINT32 eventType,
HBA_UINT32 fabricPortID), void *pUserData, HBA_HANDLE handle,
HBA_WWN PortWWN, HBA_CALLBACKHANDLE *pCallbackHandle);
HBA_STATUS HBA_RegisterForAdapterPortStatEvents(void (*pCallback)
(void *pData, HBA_WWN PortWWN, HBA_UINT32 eventType),
void *pUserData, HBA_HANDLE handle, HBA_WWN PortWWN,
HBA_PortStatistics stats, HBA_UINT32 statType,
HBA_CALLBACKHANDLE *pCallbackHandle);
HBA_STATUS HBA_RegisterForTargetEvents(void (*pCallback)
(void *pData, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN,
HBA_UINT32 eventType), void * pUserData, HBA_HANDLE handle,
HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN,
HBA_CALLBACKHANDLE *pCallbackHandle, HBA_UINT32 allTargets);
HBA_STATUS HBA_RegisterForLinkEvents(void (*pCallback)
(void *pData, HBA_WWN adapterWWN, HBA_UINT32 eventType,
void * pRLIRBuffer, HBA_UINT32 RLIRBufferSize),
void *pUserData, void *PLIRBuffer, HBA_UINT32 RLIRBufferSize,
HBA_HANDLE handle, HBA_CALLBACKHANDLE *pCallbackHandle);
SunOS 5.11 Last change: 1 Sep 2003 1
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
HBA_STATUS HBA_RemoveCallback(HBA_CALLBACKHANDLE *pCallbackHandle);
PARAMETERS
pCallback A pointer to the entry of the callback routine. pData the pUserData that is passed in from registration. This parameter can be used to correlate the event with the source of its event registration. PortWWN The Port WWN of the HBA for which the event is being reported. hbaPortWWN The Port WWN of the HBA for which the target event is being reported. discoveredPortWWN The Port WWN of the target for which the target event is being reported. adapterWWN The Port WWN of the of the HBA for which the link event is being reported. eventType a value indicating the type of event that has occured.HBA_RegisterForAdapterEvents()
Possible values are HBA_EVENT_ADAPTER_REMOVE and
HBA_EVENT_ADAPTER_CHANGE.
SunOS 5.11 Last change: 1 Sep 2003 2
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
HBA_RegisterForAdaterAddEvents()
The only possible value isHBA_EVENT_ADAPTER_ADD.
HBA_RegisterForAdaterPortEvents()
Possible values are HBA_EVENT_PORT_OFFLINE,
HBA_EVENT_PORT_ONLINE,
HBA_EVENT_PORT_NEW_TARGETS,
HBA_EVENT_PORT_FABRIC, and
HBA_EVENT_PORT_UNKNOWN.
HBA_RegisterForAdapterPortStatEvents()
Possible values areHBA_EVENT_PORT_STAT_THRESHOLD and
HBA_EVENT_PORT_STAT_GROWTH.
HBA_RegisterForTargetEvents()
If the value is HBA_EVENT_LINK_INCIDENT, RLIR
has occured and information is in the RLIR-
Buffer. If the value is HBA_EVENT_LINK_UNKNOWN,
a fabric link or topology change has occured and was not detected by RLIR. The RLIRBuffer is ignoredHBA_RegisterForLinkEvents()
Possible values are HBA_EVENT_TARGET_OFFLINE,
HBA_EVENT_TARGET_ONLINE,
HBA_EVENT_TARGET_REMOVED, and
HBA_EVENT_TARGET_UNKNOWN.
fabricPortIDIf the event is of type HBA_EVENT_PORT_FABRIC, this
parameter will be the RSCN-affected Port ID page as
defined in FC-FS. It is ignored for all other event
types. pRLIRBufferSunOS 5.11 Last change: 1 Sep 2003 3
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
A pointer to a buffer where RLIR data may be passed to the callback function. The buffer will be overwritten for each fabric link callback function, but will not be overwritten within a single call to the callback function. RLIRBufferSize Size in bytes of the RLIRBuffer. pUserData a pointer passed with each event to the callback routine that can be used to correlate the event with the source of its event registration pRLIRBuffer A pointer to a buffer where RLIR data may be passed to the callback function. The buffer will be overwritten for each fabric link callback function, but will not beoverwritten within a single call to the callback func-
tion. RLIRBufferSize Size in bytes of the RLIRBuffer. handle a handle to the HBA that event callbacks are being requested PortWWN The Port WWN of the HBA for which the event is being reported. hbaPortWWN The Port WWN of the HBA of which the event callbacks are being requested.SunOS 5.11 Last change: 1 Sep 2003 4
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
statsan HBA_PortStatistics structure which indicates the
counters to be monitored. If statType isHBA_EVENT_PORT_STAT_THRESHOLD, any non-null values are
thresholds for which to watch. If statType isHBA_EVET_PORT_STAT_GROWTH, any non-null values are
growth rate numbers over 1 minute. statTypeA value either HBA_EVENT_PORT_STAT_TRHESHOLD or
HBA_EVENT_PORT_STAT_GROWTH used to determine whether
counters registered are for threshold crossing or growth rate. discoveredPortWWN The Port WWN of the target that the event callbacks are being requested of. pCallbackHandle A pointer to structure in which an opaque identifier is returned that is used to deregister the callback. Toderegister this event, call HBA_RemoveCallback() with
this pCallbackHandle as an argument. allTargetsIf value is non-zero, discoveredPortWWN is ignored.
Events for all discovered targets will be registered by this call. If value is zero, only events for discoveredPortWWN will be registered. pcallbackHandle A handle returned by the event registration function of the routine that is to be removed.DESCRIPTION
The HBA_RegisterForAdapterEvents() function registers an
application-defined function that is called when an HBA
category asynchronous event occurs. An HBA catetory event can have one of the following event types:SunOS 5.11 Last change: 1 Sep 2003 5
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
HBA_EVENT_ADAPTER_REMOVE or HBA_EVENT_ADAPTER_CHANGE. If
either of these events occur, the callback function is called, regardless of whether the HBA handle specified atregistration is open. The HBA_RemoveCallback() function must
be called to end event delivery.The HBA_RegisterForAdapterAddEvents() function registers an
application-defined function that is called whenever an HBA
add category asynchronous event occurs. The callback func-
tion is called when a new HBA is added to the local system.The HBA_RemoveCallback() function must be called to end
event delivery.The HBA_RegisterForAdapterPortEvents() function registers an
application-defined function that is called on the specified
HBA whenever a port category asynchronous event occurs. A port catetory event can be one of the following event types:HBA_EVENT_PORT_OFFLINE, HBA_EVENT_PORT_ONLINE,
HBA_EVENT_PORT_NEW_TARGETS, HBA_EVENT_PORT_FABRIC, or
HBA_EVENT_PORT_UNKNOWN. The handle need not be open for
callbacks to occur. The HBA_RemoveCallback() function must
be called to end event delivery.The HBA_RegisterForAdapterPortStatEvents() function defines
conditions that would cause an HBA port statistics asynchro-
nous event and registers an application-defined function
that is called whenever one of these events occur. An HBAport statistics asynchronous event can be one of the follow-
ing event types: HBA_EVENT_PORT_STAT_THRESHOLD or
HBA_EVENT_PORT_STAT_GROWTH. More than one statistic can be
registered with one call by setting multiple statistics in the stats argument. For threshold events, once a specific threshold has been crossed, the callback is automatically deregistered for that statistic. The handle need not beopen for callbacks to occur. The HBA_RemoveCallback() func-
tion must be called to end event delivery.The HBA_RegisterForTargetEvents() function registers an
application-defined function that is called on the specified
HBA whenever a target category asynchronous event occurs. A Target category event can be one of the following eventtypes: HBA_EVENT_TARGET_OFFLINE, HBA_EVENT_TARGET_ONLINE,
HBA_EVENT_TARGET_REMOVED, HBA_EVENT_TARGET_UNKNOWN. The
handle need not be open for callbacks to occur. TheHBA_RemoveCallback() function must be called to end event
delivery.SunOS 5.11 Last change: 1 Sep 2003 6
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
The HBA_RegisterForLinkEvents() function registers an appli-
cation defined function that is called on the specified HBA whenever a link category asynchronous event occurs. A link category event can be one of the following event types:HBA_EVENT_LINK_INCIDENT or HBA_EVENT_LINK_UNKNOWN. RLIR ELS
is the only fabric link event type and the callback function is called whenever is it detected by the HBA. The handle need not be open for callbacks to occur. TheHBA_RemoveCallback() function must be called to end event
delivery.The HBA_RemoveCallback() function removes the
HBA_CALLBACKHANDLE instance of the callback routine.
RETURN VALUES
Upon successful completion, HBA_RegisterForAdapterEvents(),
HBA_RegisterForAdapterAddEvents(),
HBA_RegisterForAdapterPortEvents(),
HBA_RegisterForAdapterPortStatEvents(),
HBA_RegisterForTargetEvents(), and
HBA_RegisterForLinkEvents() return HBA_STATUS_OK and
pCallbackHandle may be used to deregister the callback. Oth-
erwise, an error value is returned and pCallbackHandle is not valid.Upon successful completion, HBA_RemoveCallback() returns
HBA_STATUS_OK. Otherwise, an error value is returned.
ERRORS
See libhbaapi(3LIB) for general error status values.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 1 Sep 2003 7
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| Interface Stability | Committed || ____________________________|_____________________________|_
| | Standard: FC-HBA Version 4|
| | (API version 2) ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
| Standard | FC-MI 1.92 (API version 1) |
|_____________________________|_____________________________|
SEE ALSO
libhbaapi(3LIB), attributes(5)T11 FC-MI Specification
SunOS 5.11 Last change: 1 Sep 2003 8
Common Fibre Channel HBA Information Library FunctionsHBA_RegisterForAdapterEvents(3HBAAPI)
SunOS 5.11 Last change: 1 Sep 2003 9