ANSI INCITS 399-2004 for Information Technology Fibre Channel Switch API (FC-SWAPI).pdf

1、American National StandardDeveloped byfor Information Technology Fibre Channel Switch API (FC-SWAPI)ANSI INCITS 399-2004ANSIINCITS399-2004ANSIINCITS 399-2004American National Standardfor Information Technology Fibre Channel Switch API (FC-SWAPI)SecretariatInformation Technology Industry CouncilAppro

2、ved November 29, 2004 American National Standards Institute, Inc.AbstractA standard Application Programming Interface defines a scope within which, and a grammar by which, it is possible to write application software without attention to vendor-specific infrastructure behavior. The Fibre Channel Swi

3、tch Application Programming Interface (FC-SWAPI) standard defines a standard Application Programming Interface, the scope of which is management of Fibre Channel Switches and use of specific Fibre Channel facilities for discovery and management of the components of a Fibre Channel Storage Area Netwo

4、rk. This standard is to be used in conjuction with the Fibre Channel and SCSI families of standards.Approval of an American National Standard requires review by ANSI that therequirements for due process, consensus, and other criteria for approval havebeen met by the standards developer.Consensus is

5、established when, in the judgement of the ANSI Board ofStandards Review, substantial agreement has been reached by directly andmaterially affected interests. Substantial agreement means much more thana simple majority, but not necessarily unanimity. Consensus requires that allviews and objections be

6、 considered, and that a concerted effort be madetowards their resolution.The use of American National Standards is completely voluntary; theirexistence does not in any respect preclude anyone, whether he has approvedthe standards or not, from manufacturing, marketing, purchasing, or usingproducts, p

7、rocesses, or procedures not conforming to the standards.The American National Standards Institute does not develop standards andwill in no circumstances give an interpretation of any American NationalStandard. Moreover, no person shall have the right or authority to issue aninterpretation of an Amer

8、ican National Standard in the name of the AmericanNational Standards Institute. Requests for interpretations should beaddressed to the secretariat or sponsor whose name appears on the titlepage of this standard.CAUTION NOTICE: This American National Standard may be revised orwithdrawn at any time. T

9、he procedures of the American National StandardsInstitute require that action be taken periodically to reaffirm, revise, orwithdraw this standard. Purchasers of American National Standards mayreceive current information on all standards by calling or writing the AmericanNational Standards Institute.

10、American National StandardPublished byAmerican National Standards Institute, Inc.25 West 43rd Street, New York, NY 10036Copyright 2004 by Information Technology Industry Council (ITI)All rights reserved.No part of this publication may be reproduced in anyform, in an electronic retrieval system or ot

11、herwise,without prior written permission of ITI, 1250 Eye Street NW, Washington, DC 20005. Printed in the United States of AmericaCAUTION: The developers of this standard have requested that holders of patents that may berequired for the implementation of the standard disclose such patents to the pu

12、blisher. However,neither the developers nor the publisher have undertaken a patent search in order to identifywhich, if any, patents may apply to this standard. As of the date of publication of this standardand following calls for the identification of patents that may be required for the implementa

13、tion ofthe standard, no such claims have been made. No further patent search is conducted by the de-veloper or publisher in respect to any standard it processes. No representation is made or impliedthat licenses are not required to avoid infringement in the use of this standard.iContentsPageForeword

14、 . xiii1 Scope. 12 Normative References . 22.1 Normative references . 22.2 Approved references 23 Definitions, symbols, abbreviations, and conventions 33.1 Definitions .33.2 Symbols and abbreviations 63.3 Keywords 63.4 Conventions. .73.5 Notation for Procedures and Functions 84 Common Data Definitio

15、ns and Functions. 94.1 Basic Data Types .94.1.1 Basic Data Types Overvie. 94.1.2 SWAPI_NAME_T 94.1.3 SWAPI_STRING_T . 94.1.4 SWAPI_BOOL_T. 94.1.5 SWAPI_HANDLE_T 94.1.6 SWAPI_WWN_T . 94.1.7 SWAPI_FCID_T 94.1.8 SWAPI_IPADDR_T . 104.1.9 Capability Flags . 104.2 Status Codes. .114.2.1 SWAPI_STATUS_T. 11

16、4.3 Data Structures .134.3.1 SWAPI_LIB_INFO_T. 134.3.2 SWAPI_PROD_INFO_T 134.4 General Functions. .144.4.1 General Function Overview. 144.4.2 SWAPI_Init() 144.4.3 SWAPI_Uninit() . 154.4.4 SWAPI_free() 154.4.5 SWAPI_ListLibCap() 164.4.6 SWAPI_ListLibInfo() 164.4.7 SWAPI_ListProductInfo(). 174.5 Error

17、 Processing Functions. .174.5.1 Error Processing Function Overview. 174.5.2 SWAPI_error_code() . 184.5.3 SWAPI_error_message() 185 Connection Component.195.1 Connections to Switches. .19ii5.2 Connection Data Structures195.2.1 Connection Data Structure Overview.195.2.2 SWAPI_MAX_CD_ENTRIES.195.2.3 SW

18、API_CONNDATA_TYPE_T195.2.4 SWAPI_CONNDATA_ENTRY_T.205.2.5 SWAPI_CONNATTR_T .205.2.6 SWAPI_CONNDATA_T.215.3 Connection Functions. 215.3.1 Connection Functions Overview 215.3.2 SWAPI_ListConnData() .225.3.3 SWAPI_Connect()225.3.4 SWAPI_Disconnect() .235.3.5 SWAPI_GetConnData().245.3.6 SWAPI_ListConnUn

19、itCap()256 Discovery Component. .276.1 Discovery. .276.1.1 Discovery Overview .276.1.2 Connectivity Unit Attributes276.1.3 Port Attributes 276.2 Discovery Data Structures. .276.2.1 Discovery Data Structures Overview .276.2.2 SWAPI_UNIT_STATE_T 286.2.3 SWAPI_UNIT_STATUS_T.296.2.4 SWAPI_UNIT_ATTR_T .2

20、96.2.5 SWAPI_PORT_TYPE_T306.2.6 SWAPI_PORT_STATE_T306.2.7 SWAPI_PORT_SPEED_T.316.2.8 SWAPI_PORT_ATTR_T316.2.9 SWAPI_ATTACHED_NODE_T .326.2.10 SWAPI_FABRIC_UNIT_T336.3 Discovery Functions336.3.1 Discovery Functions Overview.336.3.2 SWAPI_DsGetFabricName() .346.3.3 SWAPI_DsGetFabricUnits().346.3.4 SWA

21、PI_DsGetTopology().356.3.5 SWAPI_DsGetUnitAttributes() 366.3.6 SWAPI_DsGetPortAttributes()376.3.7 SWAPI_DsGetAllPortsAttributes() .386.4 Name Server Data Structure.396.4.1 Name Server Data Structure Overview396.4.2 SWAPI_NS_ALL_OBJECTS_T .396.4.3 SWAPI_NS_OBJ_TYPE_T406.4.4 SWAPI_NS_OBJECT_T406.4.5 S

22、WAPI_NS_KEY_TYPE_T406.4.6 SWAPI_NS_KEY_T.416.5 Name Server Functions. .416.5.1 Name Server Functions Overview .416.5.2 SWAPI_DsGetAllNext() .416.5.3 SWAPI_DsGetNameserverObjects().427 Zoning Component.44iii7.1 Zoning Overview. 447.2 Zoning Data Structures. 457.2.1 Zoning Data Structures Overview 457

23、.2.2 SWAPI_MEMBER_TYPE_T 457.2.3 SWAPI_PORT_ID_T457.2.4 SWAPI_MEMBER_T .467.2.5 SWAPI_ZONE_T .467.2.6 SWAPI_ZONESET_T 467.2.7 SWAPI_DEF_ZONE_STATE_T 477.2.8 SWAPI_LIMITATIONS_T.477.3 Zoning Functions. .487.3.1 Zoning Functions Overview .487.3.2 SWAPI_ZnTest()507.3.3 SWAPI_ZnIsManageable() 517.3.4 SW

24、API_ZnIsManageable() 527.3.5 SWAPI_ZnIsZoningActive() .537.3.6 SWAPI_ZnGetActiveZonesetName().547.3.7 SWAPI_ZnGetActiveZonesetZonesList().557.3.8 SWAPI_ZnGetActiveZoneMemberList() 567.3.9 SWAPI_ZnGetActiveZoneSetObject() .577.3.10 SWAPI_ZnGetZonesetList() 587.3.11 SWAPI_ZnGetZoneList() .597.3.12 SWA

25、PI_ZnDoesZonesetExist()607.3.13 SWAPI_ZnDoesZoneExist() 617.3.14 SWAPI_ZnGetZonesetZones() 627.3.15 SWAPI_ZnGetZoneMembers()637.3.16 SWAPI_ZnZoneInZoneset().647.3.17 SWAPI_ZnMemberInZone() 657.3.18 SWAPI_ZnZoneCreate()667.3.19 SWAPI_ZnZoneReplace() .677.3.20 SWAPI_ZnZoneDelete() 687.3.21 SWAPI_ZnZon

26、eAddMembers() .697.3.22 SWAPI_ZnZoneRemoveMembers() 707.3.23 SWAPI_ZnZonesetCreate() .717.3.24 SWAPI_ZnZonesetReplace().737.3.25 SWAPI_ZnZonesetDelete() .747.3.26 SWAPI_ZnZonesetAddZones() .757.3.27 SWAPI_ZnZonesetRemoveZones() 767.3.28 SWAPI_ZnCheckZonesetObjValidity() 787.3.29 SWAPI_ZnClearInactiv

27、eZoneData() 797.3.30 SWAPI_ZnZonesetActivate() .807.3.31 SWAPI_ZnZonesetObjActivate() .807.3.32 SWAPI_ZnZonesetDeactivate().827.3.33 SWAPI_ZnCommit() 827.3.34 SWAPI_ZnGetZoningImage() 837.3.35 SWAPI_ZnSetZoningImage() 847.3.36 SWAPI_ZnIsDefaultZoneManageable().857.3.37 SWAPI_ZnGetDefaultZoneState()

28、.867.3.38 SWAPI_ZnSetDefaultZoneState() .878 Statistics Component898.1 Statistics Overview89iv8.2 Statistics Monitoring Structures. .898.3 Statistics Data Structures948.4 Statistics Categories. 958.4.1 Statistics Categories Overview 958.4.2 SWAPI_STATS_LABEL_T 958.4.3 SWAPI_STATS_CAPABILITIES_T .958

29、.4.4 SWAPI_STATS_PORT_REF_TYPE_T.958.4.5 SWAPI_STATS_PORT_REF_T 968.4.6 SWAPI_INT64968.4.7 SWAPI_STATS_ENTRY_T .968.4.8 SWAPI_STATS_PORT_SNAPSHOT_T978.4.9 SWAPI_STATS_SNAPSHOT_T978.5 Statistics Functions.978.5.1 Statistics Functions List .978.5.2 Statistics Overview.988.5.3 SWAPI_StatsCapabilities (

30、) .988.5.4 SWAPI_StatsSetRatesInterval() 1008.5.5 SWAPI_StatGetSnapshot ().1008.5.6 SWAPI_StatsResetStatistics ()1029 Unit Control.1039.1 Unit Control Overview.1039.2 Unit Control Data Types1039.2.1 Unit Control Data Types Overview.1039.2.2 SWAPI_IMAGE_TYPE_T 1049.2.3 SWAPI_PRINCIPAL_PRIORITY_T .104

31、9.2.4 SWAPI_AUTHORITY_T 1049.2.5 SWAPI_USER_INFO_T.1049.2.6 SWAPI_DOWNLOAD_STAGE_T1059.2.7 SWAPI_IPADDR_RESMODE_T .1059.2.8 SWAPI_IPADDR_CONFIG_T1069.2.9 SWAPI_UNIT_CONFIG_CAPS_T.1069.2.10 SWAPI_PORT_CONFIG_CAPS_T .1089.2.11 SWAPI_ACL_CAPS_T 1099.2.12 SWAPI_IP_CONFIG_CAPS_T1109.3 Unit Control Functi

32、ons. .1109.3.1 Unit Control Functions Overview .1109.3.2 SWAPI_UcTest()1129.3.3 SWAPI_UcAclConfigCapabilities().1129.3.4 SWAPI_UcGetUserList ().1139.3.5 SWAPI_UcAddUser ()1149.3.6 SWAPI_UcRemoveUser ().1159.3.7 SWAPI_UcChangeUserPassword().1169.3.8 SWAPI_UcUnitConfigCapabilities() .1179.3.9 SWAPI_Uc

33、UnitConfigGetName() 1189.3.10 SWAPI_UcUnitConfigSetName().1199.3.11 SWAPI_UcUnitConfigGetDomainID()1199.3.12 SWAPI_UcUnitConfigSetDomainID() 1209.3.13 SWAPI_UcUnitConfigGetDomainIDLocked() 1219.3.14 SWAPI_UcUnitConfigSetDomainIDLocked().1229.3.15 SWAPI_UcUnitConfigGetPrincipalPriority().123v9.3.16 S

34、WAPI_UcUnitConfigSetPrincipalPriority1249.3.17 SWAPI_DOWNLOAD_IMAGE_CALLBACK_T1259.3.18 SWAPI_UcDownloadImage().1269.3.19 SWAPI_UcUnitSetOnline() 1279.3.20 SWAPI_UcUnitSetOffline() 1289.3.21 SWAPI_UcUnitForceReset()1299.3.22 SWAPI_UcIpConfigCapabilities().1299.3.23 SWAPI_UcIpConfigCapabilities() Ove

35、rview.1299.3.24 SWAPI_UcIpConfigGetAddress() 1309.3.25 SWAPI_UcIpConfigSetAddress().1319.3.26 SWAPI_UcIpConfigGetAddressResMode().1329.3.27 SWAPI_UcIpConfigSetAddressResMode() .1339.3.28 SWAPI_UcPortConfigCapabilities() .1349.3.29 SWAPI_UcPortConfigGetName() 1359.3.30 SWAPI_UcPortConfigSetName().136

36、9.3.31 SWAPI_UcPortConfigGetState() .1379.3.32 SWAPI_UcPortConfigSetState()1389.3.33 SWAPI_UcPortConfigGetType()1399.3.34 SWAPI_UcPortConfigSetType() 1409.3.35 SWAPI_UcPortConfigGetLinkSpeed().1419.3.36 SWAPI_UcPortConfigSetLinkSpeed() .1429.3.37 SWAPI_UcPortForceLIP() .1439.3.38 SWAPI_UcPortForceRe

37、set() .14410 Events.14510.1 Events Overview. 14510.2 Events Data Types14510.2.1 Events Data Types Overview.14510.2.2 SWAPI_EVENT_CODE_T.14510.2.3 SWAPI_EVENT_TYPE_T14810.2.4 SWAPI_EVENT_DATA_HW_T14810.2.5 SWAPI_EVENT_DATA_CN_T 14910.2.6 SWAPI_EVENT_SEVERITY_T .14910.2.7 SWAPI_EVENT_DATA_ALARM_T .149

38、10.2.8 SWAPI_EVENT_T .15010.3 Events Functions. 15010.3.1 Events Functions Overview 15010.3.2 SWAPI_EvTest()15110.3.3 SWAPI_EvSupportedEvents() .15110.3.4 SWAPI_EVENT_CALLBACK_T 15210.3.5 SWAPI_EvRegisterForEvents() .15310.3.6 SWAPI_EvRegisterForEvents() Overview .15310.3.7 SWAPI_EvDeregisterForEven

39、ts()15411 Hardware. .15611.1 Hardware Overview. .15611.2 Hardware Data Types. 15611.2.1 Hardware Data Types Overview 15611.2.2 SWAPI_NOT_MOUNTED15611.2.3 SWAPI_COMPONENT_LOCATION_T .15611.2.4 SWAPI_COMPONENT_ROLE_T 15711.2.5 SWAPI_COMPONENT_STATUS_T158vi11.2.6 SWAPI_COMPONENT_TYPE_T 15811.2.7 SWAPI_

40、COMPONENT_T15911.2.8 SWAPI_SLOT_TYPE_T 16011.2.9 SWAPI_CHASSIS_SLOT_T16011.2.10 SWAPI_TEMP_STATUS_T.16111.2.11 SWAPI_TEMP_SENSOR_T16111.2.12 SWAPI_CHASSIS_T .16111.3 Hardware Functions.16211.3.1 Hardware Functions Overview16211.3.2 SWAPI_HwTest().16211.3.3 SWAPI_HwGetComponents()16311.3.4 SWAPI_HwGe

41、tComponentsByType() .16411.3.5 SWAPI_HwGetComponentByLocation()16511.3.6 SWAPI_HwGetSlots()16611.3.7 SWAPI_HwGetSlots() Overview16611.3.8 SWAPI_HwGetSlotsByType()16711.3.9 SWAPI_HwGetTempSensors()16811.3.10 SWAPI_HwGetChassis() .16912 Routing. 17112.1 Routing Overview17112.2 Routing Data Types. .171

42、12.2.1 Routing Data Types Overview .17112.2.2 SWAPI_LSR_LINK_T 17112.2.3 SWAPI_LSR_SWITCH_T17212.2.4 SWAPI_PORT_ROUTE_T.17212.2.5 SWAPI_ROUTE_T.17312.3 Routing Functions17312.3.1 Routing Functions Overview.17312.3.2 SWAPI_RtTest() 17312.3.3 SWAPI_RtGetTopologyDB()17412.3.4 SWAPI_RtGetRoutingTable()

43、17512.3.5 SWAPI_RtGetRoute()176Tables1. Call Categories .102. SWAPI_STATUS_T Codes.113. General Functions.144. Error Processing Functions.175. Connection Data Structure196. SWAPI_CONNDATA_TYPE_T Enumerated Values207. Connection Functions .218. SWAPI_Connect() Return Status Values239. SWAPI_Disconnec

44、t() Return Status Values .2410. SWAPI_GetConnData() Return Status Values .2511. SWAPI_ListConnUnitCap() Return Status Values2612. Discovery Data Structures 28vii13. SWAPI UNIT STATE_T Enumerations .2814. SWAPI_UNIT_STATUS_T Enumerations 2915. SWAPI_PORT_TYPE_T Enumerations3016. SWAPI_PORT_STATE_T En

45、umerations .3017. SWAPI_PORT_SPEED_T Enumerations.3118. Discovery Functions.3319. SWAPI_DsGetFabricName () Return Status Values 3420. SWAPI_DsGetFabricUnits () Return Status Values3521. SWAPI_DsGetTopology () Return Status Values .3622. SWAPI_DsGetUnitAttributes () Return Status Values 3723. SWAPI_D

46、sGetPortAttributes () Return Status Values 3824. SWAPI_DsGetAllPortsAttributes () Return Status Values 3825. Name Server Data Structures.3926. SWAPI_NS_OBJ_TYPE_T Enumerations4027. SWAPI_NS_KEY_TYPE_T Enumerations .4028. Name Server Functions 4129. SWAPI_DsGetAllNext () Return Status Values 4230. SW

47、API_DsGetNameserverObjects () Return Status Values 4331. Zoning Data Structures .4532. SWAPI_MEMBER_TYPE_T Enumerators .4533. SWAPI_DEF_ZONE_STATE_T Enumerators4734. Zoning Functions 4935. SWAPI_ZnTest() Return Status Values5136. SWAPI_ZnIsManageable() Return Status Values 5237. SWAPI_ZnGetLimitatio

48、ns() Return Status Values5338. SWAPI_ZnIsZoningActive() Return Status Values .5439. SWAPI_ZnGetActiveZonesetName() Return Status Values.5540. SWAPI_ZnGetActiveZonesetZonesList() Return Status Values.5641. SWAPI_ZnGetActiveZoneMemberList() Return Status Values 5742. SWAPI_ZnZonesetObjActivate() Retur

49、n Status Values .5843. SWAPI_ZnGetZonesetList() Return Status Values 5944. SWAPI_ZnGetZoneList() Return Status Values .6045. SWAPI_ZnDoesZonesetExist() Return Status Values6146. SWAPI_ZnDoesZoneExist() Return Status Values 6247. SWAPI_ZnGetZonesetZones() Return Status Values 6348. SWAPI_ZnGetZoneMembers() Return Status Values64viii49. SWAPI_ZnZoneInZoneset() Return Status Values.6550. SWAPI_ZnMemberInZone() Return Status Values 6651. SWAPI_ZnZoneCreate() Return Status Values6752. SWAPI_ZnZoneReplace() Return Status Values .6853. SWAPI_ZnZoneDelete() Return Status Values 6954. SWAPI_ZnZon