HBA_RegisterForAdapterPortStatEvents routine

The HBA_RegisterForAdapterPortStatEvents routine registers the indicated user callback routine to call when a port statistics event occurs.

Syntax

HBA_STATUS HBA_API HBA_RegisterForAdapterPortStatEvents(
   HBA_PORTSTAT_CALLBACK callback,
   void                  *userData,
   HBA_HANDLE            handle,
   HBA_WWN               PortWWN,
   PHBA_PORTSTATISTICS   stats,
   HBA_UINT32            statType,
   HBA_CALLBACKHANDLE    *callbackHandle
);

Parameters

  • callback
    Pointer to a callback routine of type HBA_PORTSTAT_CALLBACK that is called when an adapter is added to the system.

  • userData
    Pointer to a buffer that is passed to the callback routine with each event. This data correlates the event with the source of the event registration.

  • handle
    Contains a value returned by the routine HBA_OpenAdapter that identifies the HBA for which the adapter events are generated.

  • PortWWN
    Contains a 64-bit worldwide name (WWN) that uniquely identifies the HBA port from which port events are reported. For a discussion of worldwide names, see the T11 committee's Fibre Channel HBA API specification.

  • stats
    Pointer to a structure of type HBA_PortStatistics that, on input, holds the statistical levels that determine when port statistics events are generated. On output, this member holds statistical data gathered for the port referenced by PortWWN.

  • statType
    Holds a value that indicates the mechanism used to trigger port statistics events. If the value is HBA_EVENT_PORT_STAT_THRESHOLD, then each non-NULL member of the HBA_PortStatistics structure pointed to by stats will indicate the threshold at which an event is generated for that particular statistical parameter. For example, if the TxWords member of the HBA_PortStatistics structure holds a value of 1,000,000, then an event will be generated once 1,000,000 words have been transmitted.

    If the value of statType is HBA_EVENT_PORT_STAT_GROWTH, then the values in the HBA_PortStatistics structure will be interpreted as growth-rate numbers. The T11 committee's Fibre Channel HBA API specification recommends that port statistics be checked once a minute, and if the value or a given statistics parameter has grown by more than the number indicated for that parameter in HBA_PortStatistics, an event is generated, but the actual frequency with which growth is monitored is hardware-specific.

  • callbackHandle
    Pointer to an opaque identifier that the user must pass to HBA_RemoveCallback to de-register the callback routine.

Return value

The HBA_RegisterForAdapterPortStatEvents routine returns a value of type HBA_STATUS that indicates the status of the HBA. In particular, this member should have one of the following values.

Return code Description
HBA_STATUS_OK

Returned if the callback routine was successfully registered.

HBA_STATUS_ERROR_ILLEGAL_WWN

Returned if the HBA referenced by handle does not have a port with a name that matches the value in PortWWN.

HBA_STATUS_ERROR_NOT_SUPPORTED

Returned if the hardware does not support statistic events.

HBA_STATUS_ERROR

Returned if an unspecified error occurred that prevented the registration of the callback routine.

 

Requirements

Target platform

Desktop

Header

Hbaapi.h (include Hbaapi.h)

Library

Hbaapi.lib

DLL

Hbaapi.dll

See also

HBA_OpenAdapter

HBA_PORTSTAT_CALLBACK

HBA_PortStatistics

HBA_STATUS

 

 

Send comments about this topic to Microsoft