Current File : //usr/share/man/man3hbaapi/HBA_RegisterForAdapterEvents.3hbaapi

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.TH HBA_RegisterForAdapterEvents 3HBAAPI "1 Sep 2003" "SunOS 5.11" "Common Fibre Channel HBA Information Library Functions"
.SH NAME
HBA_RegisterForAdapterEvents, HBA_RegisterForAdapterAddEvents, HBA_RegisterForAdapterPortEvents, HBA_RegisterForAdapterPortStatEvents, HBA_RegisterForTargetEvents, HBA_RegisterForLinkEvents, HBA_RemoveCallback \- SNIA event handling functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lHBAAPI\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <hbaapi.h>

\fBHBA_STATUS\fR \fBHBA_RegisterForAdapterEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIPortWWN\fR, \fBHBA_UINT32\fR \fIeventType\fR),
     \fBvoid *\fR\fIpUserData\fR, \fBHBA_HANDLE\fR \fIhandle\fR,
     \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RegisterForAdapterAddEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIPortWWN\fR, \fBHBA_UINT32\fR \fIeventType\fR),
     \fBvoid *\fR\fIpUserData\fR, \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RegisterForAdapterPortEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIPortWWN\fR, \fBHBA_UINT32\fR \fIeventType\fR,
     \fBHBA_UINT32\fR \fIfabricPortID\fR), \fBvoid *\fR\fIpUserData\fR, \fBHBA_HANDLE\fR \fIhandle\fR,
     \fBHBA_WWN\fR \fIPortWWN\fR, \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RegisterForAdapterPortStatEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIPortWWN\fR, \fBHBA_UINT32\fR \fIeventType\fR),
     \fBvoid *\fR\fIpUserData\fR, \fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIPortWWN\fR,
     \fBHBA_PortStatistics\fR \fIstats\fR, \fBHBA_UINT32\fR \fIstatType\fR,
     \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RegisterForTargetEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR, \fBHBA_WWN\fR \fIdiscoveredPortWWN\fR,
     \fBHBA_UINT32\fR \fIeventType\fR), \fBvoid *\fR \fIpUserData\fR, \fBHBA_HANDLE\fR \fIhandle\fR,
     \fBHBA_WWN\fR \fIhbaPortWWN\fR, \fBHBA_WWN\fR \fIdiscoveredPortWWN\fR,
     \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR, \fBHBA_UINT32\fR \fIallTargets\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RegisterForLinkEvents\fR(\fBvoid (*\fR\fIpCallback\fR)
     (\fBvoid *\fR\fIpData\fR, \fBHBA_WWN\fR \fIadapterWWN\fR, \fBHBA_UINT32\fR \fIeventType\fR,
     \fBvoid *\fR \fIpRLIRBuffer\fR, \fBHBA_UINT32\fR \fIRLIRBufferSize\fR),
     \fBvoid *\fR\fIpUserData\fR, \fBvoid *\fR\fIPLIRBuffer\fR, \fBHBA_UINT32\fR \fIRLIRBufferSize\fR,
     \fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_RemoveCallback\fR(\fBHBA_CALLBACKHANDLE *\fR\fIpCallbackHandle\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIpCallback\fR\fR
.ad
.sp .6
.RS 4n
A pointer to the entry of the callback routine.
.sp
.ne 2
.mk
.na
\fB\fIpData\fR\fR
.ad
.sp .6
.RS 4n
the \fIpUserData\fR that is passed in from registration. This parameter can be used to correlate the event with the source of its event registration.
.RE

.sp
.ne 2
.mk
.na
\fB\fIPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the HBA for which the event is being reported.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhbaPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the HBA for which the target event is being reported.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdiscoveredPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the target for which the target event is being reported.
.RE

.sp
.ne 2
.mk
.na
\fB\fIadapterWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the of the HBA for which the link event is being reported.
.RE

.sp
.ne 2
.mk
.na
\fB\fIeventType\fR\fR
.ad
.sp .6
.RS 4n
a value indicating the type of event that has occured.
.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForAdapterEvents()\fR\fR
.ad
.sp .6
.RS 4n
Possible values are \fBHBA_EVENT_ADAPTER_REMOVE\fR and \fBHBA_EVENT_ADAPTER_CHANGE\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForAdaterAddEvents()\fR\fR
.ad
.sp .6
.RS 4n
The only possible value is \fBHBA_EVENT_ADAPTER_ADD\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForAdaterPortEvents()\fR\fR
.ad
.sp .6
.RS 4n
Possible values are \fBHBA_EVENT_PORT_OFFLINE\fR, \fBHBA_EVENT_PORT_ONLINE\fR, \fBHBA_EVENT_PORT_NEW_TARGETS\fR, \fBHBA_EVENT_PORT_FABRIC\fR, and \fBHBA_EVENT_PORT_UNKNOWN\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForAdapterPortStatEvents()\fR\fR
.ad
.sp .6
.RS 4n
Possible values are \fBHBA_EVENT_PORT_STAT_THRESHOLD\fR and \fBHBA_EVENT_PORT_STAT_GROWTH\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForTargetEvents()\fR\fR
.ad
.sp .6
.RS 4n
If the value is \fBHBA_EVENT_LINK_INCIDENT\fR, RLIR has occured and information is in the RLIRBuffer.  If the value is \fBHBA_EVENT_LINK_UNKNOWN\fR, a fabric link or topology change has occured and was not detected by RLIR.  The RLIRBuffer is ignored
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_RegisterForLinkEvents()\fR\fR
.ad
.sp .6
.RS 4n
Possible values are \fBHBA_EVENT_TARGET_OFFLINE\fR, \fBHBA_EVENT_TARGET_ONLINE\fR, \fBHBA_EVENT_TARGET_REMOVED\fR, and \fBHBA_EVENT_TARGET_UNKNOWN\fR.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIfabricPortID\fR\fR
.ad
.sp .6
.RS 4n
If the event is of type \fBHBA_EVENT_PORT_FABRIC\fR, this parameter will be the RSCN-affected Port ID page as defined in FC-FS.  It is ignored for all other event types.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpRLIRBuffer\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.mk
.na
\fB\fIRLIRBufferSize\fR\fR
.ad
.sp .6
.RS 4n
Size in bytes of the RLIRBuffer.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIpUserData\fR\fR
.ad
.sp .6
.RS 4n
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
.RE

.sp
.ne 2
.mk
.na
\fB\fIpRLIRBuffer\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.mk
.na
\fB\fIRLIRBufferSize\fR\fR
.ad
.sp .6
.RS 4n
Size in bytes of the RLIRBuffer.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhandle\fR\fR
.ad
.sp .6
.RS 4n
a handle to the HBA that event callbacks are being requested
.RE

.sp
.ne 2
.mk
.na
\fB\fIPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the HBA for which the event is being reported.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhbaPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the HBA of which the event callbacks are being requested.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstats\fR\fR
.ad
.sp .6
.RS 4n
an HBA_PortStatistics structure which indicates the counters to be monitored.  If \fIstatType\fR is \fBHBA_EVENT_PORT_STAT_THRESHOLD\fR, any non-null values are thresholds for which to watch.  If \fIstatType\fR is \fBHBA_EVET_PORT_STAT_GROWTH\fR, any non-null values are growth rate numbers over 1 minute.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatType\fR\fR
.ad
.sp .6
.RS 4n
A value either \fBHBA_EVENT_PORT_STAT_TRHESHOLD\fR or \fBHBA_EVENT_PORT_STAT_GROWTH\fR used to determine whether counters registered are for threshold crossing or growth rate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdiscoveredPortWWN\fR\fR
.ad
.sp .6
.RS 4n
The Port WWN of the target that the event callbacks are being requested of.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpCallbackHandle\fR\fR
.ad
.sp .6
.RS 4n
A pointer to structure in which an opaque identifier is returned that is used to deregister the callback. To deregister this event, call \fBHBA_RemoveCallback()\fR with this \fIpCallbackHandle\fR as an argument.
.RE

.sp
.ne 2
.mk
.na
\fB\fIallTargets\fR\fR
.ad
.sp .6
.RS 4n
If value is non-zero, \fIdiscoveredPortWWN\fR is ignored.  Events for all discovered targets will be registered by this call.  If value is zero, only events for \fIdiscoveredPortWWN\fR will be registered.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpcallbackHandle\fR\fR
.ad
.sp .6
.RS 4n
A handle returned by the event registration function of the routine that is to be removed.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBHBA_RegisterForAdapterEvents()\fR 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: \fBHBA_EVENT_ADAPTER_REMOVE\fR or \fBHBA_EVENT_ADAPTER_CHANGE\fR. If either of these events occur, the callback function is called, regardless of whether the HBA handle specified at registration is open. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RegisterForAdapterAddEvents()\fR function registers an application-defined function that is called whenever an HBA add category asynchronous event occurs.  The callback function is called when a new HBA is added to the local system. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RegisterForAdapterPortEvents()\fR 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: \fBHBA_EVENT_PORT_OFFLINE\fR, \fBHBA_EVENT_PORT_ONLINE\fR, \fBHBA_EVENT_PORT_NEW_TARGETS\fR, \fBHBA_EVENT_PORT_FABRIC\fR, or \fBHBA_EVENT_PORT_UNKNOWN\fR.  The handle need not be open for callbacks to occur. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RegisterForAdapterPortStatEvents()\fR function defines conditions that would cause an HBA port statistics asynchronous event and registers an application-defined function that is called whenever one of these events occur. An HBA port statistics asynchronous event can be one of the following event types:  \fBHBA_EVENT_PORT_STAT_THRESHOLD\fR or \fBHBA_EVENT_PORT_STAT_GROWTH\fR.  More than one statistic can be registered with one call by setting multiple statistics in the \fIstats\fR argument.  For threshold events, once a specific threshold has been crossed, the callback is automatically deregistered for that statistic.  The handle need not be open for callbacks to occur. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RegisterForTargetEvents()\fR 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 event types: \fBHBA_EVENT_TARGET_OFFLINE\fR, \fBHBA_EVENT_TARGET_ONLINE\fR, \fBHBA_EVENT_TARGET_REMOVED\fR, \fBHBA_EVENT_TARGET_UNKNOWN\fR.  The handle need not be open for callbacks to occur. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RegisterForLinkEvents()\fR function registers an application 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: \fBHBA_EVENT_LINK_INCIDENT\fR or \fBHBA_EVENT_LINK_UNKNOWN\fR.  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. The \fBHBA_RemoveCallback()\fR function must be called to end event delivery.
.sp
.LP
The \fBHBA_RemoveCallback()\fR function removes the \fBHBA_CALLBACKHANDLE\fR instance of the callback routine.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBHBA_RegisterForAdapterEvents()\fR, \fBHBA_RegisterForAdapterAddEvents()\fR, \fBHBA_RegisterForAdapterPortEvents()\fR, \fBHBA_RegisterForAdapterPortStatEvents()\fR, \fBHBA_RegisterForTargetEvents()\fR, and \fBHBA_RegisterForLinkEvents()\fR return \fBHBA_STATUS_OK\fR and \fIpCallbackHandle\fR may be used to deregister the callback. Otherwise, an error value is returned and \fIpCallbackHandle\fR is not valid.
.sp
.LP
Upon successful completion, \fBHBA_RemoveCallback()\fR returns \fBHBA_STATUS_OK\fR. Otherwise, an error value is returned.
.SH ERRORS
.sp
.LP
See \fBlibhbaapi\fR(3LIB) for general error status values.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
T{
Standard: FC-HBA Version 4 (API version 2)
T}
_
MT-LevelSafe
_
StandardFC-MI 1.92 (API version 1)
.TE

.SH SEE ALSO
.sp
.LP
\fBlibhbaapi\fR(3LIB), \fBattributes\fR(5)
.sp
.LP
T11 FC-MI Specification