1 /******************************************************************************
2  *
3  * Description
4  *  mpapi.h - general header file for Multipath Management API Version 1.0
5  *  client
6  *
7  * License:
8  *  The contents of this file are subject to the SNIA Public License
9  *  Version 1.1 (the "License"); you may not use this file except in
10  *  compliance with the License. You may obtain a copy of the License at
11  *
12  *  http://mp-mgmt-api.sourceforge.net
13  *
14  *  Software distributed under the License is distributed on an "AS IS"
15  *  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
16  *  the License for the specific language governing rights and limitations
17  *  under the License.
18  *
19  * The Original Code is  SNIA iSCSI Management API and Multipath Management API
20  *	general header file
21  *
22  * The Initial Developer of the Original Code is:
23  *	Benjamin F. Kuo Troika Networks, Inc. (benk@troikanetworks.com)
24  *	David Dillard	VERITAS Software(david.dillard@veritas.com)
25  *	Jeff Ding	Adaptec, Inc. (jding@corp.adaptec.com)
26  *	Dave Wysochanski Network Appliance, Inc. (davidw@netapp.com)
27  *      Hyon Kim       	Sun Microsystems(hyon.kim@sun.com)
28  *
29  * Contributor(s):
30  *	Paul von Behren Sun Microsystems(paul.vonbehren@sun.com)
31  *
32  ******************************************************************************
33  *
34  *   Changes:
35  *  1/15/2005   Implemented SNIA MP API specification 1.0
36  *  10/11/2005
37  *		- Added the license location in the header comment.
38  *	  	- Added an implementation note in constants and macros
39  *		  declarations section.
40  *		- Fixed field name value in struct _MP_PROPRIETARY_PROPERTY.
41  *		- Fixed typo in logicalUnitGroupID in
42  *		  _MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES
43  *		- Fixed typo in desiredState in struct _MP_TPG_STATE_PAIR.
44  *		- Fixed typo in API name MP_GetTargetPortGroupProperties.
45  *		- Clarified description of MP_STATUS_INVALID_PARAMETER error
46  *		  in MP_GetObjectType().
47  *		- Fixed typo in API name
48  *		  MP_GetProprietaryLoadBalanceProperties().
49  *  3/6/2006
50  *		- mpapi.h header file is updated for
51  *		  MP_LOAD_BALANCE_TYPE change in the spec.
52  *****************************************************************************/
53 
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57 
58 
59 #ifndef MPAPI_H
60 #define MPAPI_H
61 
62 #include <time.h>
63 #include <wchar.h>
64 #include <string.h>
65 #include <stdlib.h>
66 
67 
68 /* Library version string */
69 #define MP_LIBVERSION 1
70 
71 /**
72  *******************************************************************************
73  *
74  * Generic MP Constant Definitions
75  *
76  *******************************************************************************
77  */
78 #define RL_LIBRARY_SEQNUM           0
79 
80 /**
81 * Value which can be assigned to an MP_BOOL and or an MP_XBOOL.
82 */
83 #define MP_TRUE        1
84 
85 /**
86 * Value which can be assigned to an MP_BOOL and or an MP_XBOOL.
87 */
88 #define MP_FALSE       0
89 
90 /**
91 * Value which can be assigned to an MP_XBOOL.
92 */
93 #define MP_UNKNOWN     0xFFFFFFFF
94 
95 #define MP_MAX_NUM_PLUGINS	64
96 #define MP_OBJECT_TYPE_MATCH	1
97 #define MP_OBJECT_TYPE_ANY	2
98 #define MAX_NAME_SIZE		256
99 #define MAX_LINE_SIZE		515
100 
101 
102 /**
103  ******************************************************************************
104  *
105  * Base MP API Type Definitions
106  *
107  ******************************************************************************
108  */
109 
110 typedef unsigned char   MP_UINT8;  /* unsigned  8 bits */
111 typedef char            MP_INT8;   /* signed    8 bits */
112 typedef unsigned short  MP_UINT16; /* unsigned 16 bits */
113 typedef short           MP_INT16;  /* signed   16 bits */
114 typedef unsigned int    MP_UINT32; /* unsigned 32 bits */
115 typedef int             MP_INT32;  /* signed   32 bits */
116 typedef void*           MP_PVOID;  /* pointer  to void */
117 typedef MP_UINT32       MP_VOID32; /* opaque   32 bits */
118 typedef long long	MP_INT64;  /* signed   64 bits */
119 typedef unsigned long long	 MP_UINT64; /* unsigned 64 bits */
120 
121 /**
122  * A character.
123  */
124 typedef char MP_CHAR;
125 
126 /**
127  * A wide character.
128  */
129 typedef wchar_t MP_WCHAR;
130 
131 /**
132  * An unsigned character.
133  */
134 typedef unsigned char MP_BYTE;
135 
136 /**
137  * A boolean.
138  */
139 typedef MP_UINT32 MP_BOOL;
140 
141 /**
142  * An extended boolean: can have the values @ref MP_TRUE, @ref MP_FALSE, and
143  * @ref MP_UNKNOWN.
144  */
145 typedef MP_UINT32 MP_XBOOL;
146 
147 /**
148  ******************************************************************************
149  *
150  * Constants and macros declarations related to MP_STATUS
151  * Implementation Notes:  This library does validation for OID argument and
152  *			  returns the following errors.
153  *
154  *		1. MP_STATUS_INVALID_OBJECT_TYPE when input OID type is not
155  *		   one of legitimate types defined SNIA Multipath Management
156  *		   Spec.
157  *		2. MP_STATUS_INVALID_PARAMETER when input OID type is
158  *		   legitimate but not a proper type for API.
159  *		3. MP_STATUS_OBJECT_NOT_FOUND when the ownerId of input OID is
160  *		   not found or no object instance with matching
161  *		   sequenceNumber is found.
162  *		   The ownerId is validated by the common library and the
163  *		   sequence number is validated by the plugin library.
164  *
165  ******************************************************************************
166  */
167 typedef enum {
168     MP_STATUS_SUCCESS               = 0,
169     MP_STATUS_INVALID_PARAMETER     = 1,
170     MP_STATUS_UNKNOWN_FN	    = 2,
171     MP_STATUS_FAILED                = 3,
172     MP_STATUS_INSUFFICIENT_MEMORY   = 4,
173     MP_STATUS_INVALID_OBJECT_TYPE   = 5,
174     MP_STATUS_OBJECT_NOT_FOUND      = 6,
175     MP_STATUS_UNSUPPORTED           = 7,
176     MP_STATUS_FN_REPLACED           = 8,
177     MP_STATUS_ACCESS_STATE_INVALID  = 9,
178     MP_STATUS_INVALID_WEIGHT        = 10,
179     MP_STATUS_PATH_NONOPERATIONAL   = 11,
180     MP_STATUS_TRY_AGAIN		    = 12,
181     MP_STATUS_NOT_PERMITTED	    = 13
182 
183 } MP_STATUS;
184 
185 /**
186  ******************************************************************************
187  *
188  * Declaration of the MP_PATH_STATE constants
189  *
190  ******************************************************************************
191  */
192 #define MP_PATH_STATE_OKAY	    0
193 #define MP_PATH_STATE_PATH_ERR      1
194 #define MP_PATH_STATE_LU_ERR        2
195 #define MP_PATH_STATE_RESERVED      3
196 #define MP_PATH_STATE_REMOVED       4
197 #define MP_PATH_STATE_TRANSITIONING 5
198 #define MP_PATH_STATE_OPERATIONAL_CLOSED    6
199 #define MP_PATH_STATE_INVALID_CLOSED	    7
200 #define MP_PATH_STATE_OFFLINE_CLOSED	    8
201 #define MP_PATH_STATE_UNKNOWN       	    9
202 
203 typedef MP_UINT32 MP_PATH_STATE;
204 
205 /**
206  *******************************************************************************
207  *
208  * Declaration of the MP_OBJECT_TYPE constants
209  *
210  *******************************************************************************
211  */
212 #define MP_OBJECT_TYPE_UNKNOWN              0
213 #define MP_OBJECT_TYPE_PLUGIN               1
214 #define MP_OBJECT_TYPE_INITIATOR_PORT       2
215 #define MP_OBJECT_TYPE_TARGET_PORT          3
216 #define MP_OBJECT_TYPE_MULTIPATH_LU         4
217 #define MP_OBJECT_TYPE_PATH_LU              5
218 #define MP_OBJECT_TYPE_DEVICE_PRODUCT       6
219 #define MP_OBJECT_TYPE_TARGET_PORT_GROUP    7
220 #define MP_OBJECT_TYPE_PROPRIETARY_LOAD_BALANCE	8
221 
222 /* set to the highest constant of object type. */
223 #define MP_OBJECT_TYPE_MAX          8
224 
225 typedef MP_UINT32 MP_OBJECT_TYPE;
226 
227 /**
228  *******************************************************************************
229  *
230  * Declaration of the MP_PORT_TRANSPORT_TYPE
231  *
232  *******************************************************************************
233  */
234 #define MP_PORT_TRANSPORT_TYPE_UNKNOWN  0
235 #define MP_PORT_TRANSPORT_TYPE_MPNODE   1
236 #define MP_PORT_TRANSPORT_TYPE_FC       2
237 #define MP_PORT_TRANSPORT_TYPE_SPI      3
238 #define MP_PORT_TRANSPORT_TYPE_ISCSI    4
239 #define MP_PORT_TRANSPORT_TYPE_IFB      5
240 
241 typedef MP_UINT32 MP_PORT_TRANSPORT_TYPE;
242 
243 /**
244  *******************************************************************************
245  *
246  * Declaration of the MP_ACCESS_STATE_TYPE constants
247  *
248  *******************************************************************************
249  */
250 #define MP_ACCESS_STATE_ACTIVE_OPTIMIZED    (0x0)
251 #define MP_ACCESS_STATE_ACTIVE_NONOPTIMIZED (0x1)
252 #define MP_ACCESS_STATE_STANDBY             (0x2)
253 #define MP_ACCESS_STATE_UNAVAILABLE         (0x3)
254 #define MP_ACCESS_STATE_TRANSITIONING       (0xF)
255 #define MP_ACCESS_STATE_ACTIVE              (0x10)
256 
257 typedef MP_UINT32 MP_ACCESS_STATE_TYPE;
258 
259 /**
260  *******************************************************************************
261  *
262  * Declaration of the MP_LOAD_BALANCE_TYPE constants
263  *
264  *******************************************************************************
265  */
266 #define MP_LOAD_BALANCE_TYPE_UNKNOWN        (1<<0)
267 #define MP_LOAD_BALANCE_TYPE_ROUNDROBIN     (1<<1)
268 #define MP_LOAD_BALANCE_TYPE_LEASTBLOCKS    (1<<2)
269 #define MP_LOAD_BALANCE_TYPE_LEASTIO        (1<<3)
270 #define MP_LOAD_BALANCE_TYPE_DEVICE_PRODUCT (1<<4)
271 #define MP_LOAD_BALANCE_TYPE_LBA_REGION     (1<<5)
272 #define MP_LOAD_BALANCE_TYPE_FAILOVER_ONLY  (1<<6)
273 /**
274  * Proprietary load balance type should start from 0x10000(1<<16) or greater.
275  * It is exposed through API MP_GetProprietaryLoadBalanceProperties if exists.
276  */
277 
278 typedef MP_UINT32 MP_LOAD_BALANCE_TYPE;
279 
280 typedef struct mpPluginInfo {
281       MP_WCHAR        pluginName[MAX_NAME_SIZE];
282       MP_CHAR         pluginPath[MAX_NAME_SIZE];
283       void*           hdlPlugin;
284       MP_UINT32       ownerId;
285 } MPPLUGININFO_T;
286 
287 
288 /**
289  *******************************************************************************
290  *
291  * Declaration of the MP_PROPRIETARY_PROPERTY
292  *
293  *******************************************************************************
294  */
295 typedef struct _MP_PROPRIETARY_PROPERTY
296 {
297     MP_WCHAR                name[16];
298     MP_WCHAR                value[48];
299 
300 } MP_PROPRIETARY_PROPERTY;
301 
302 /**
303  *******************************************************************************
304  *
305  * Declaration of the MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES
306  *
307  *******************************************************************************
308  */
309 typedef struct _MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES
310 {
311     MP_LOAD_BALANCE_TYPE    typeIndex;
312     MP_WCHAR                name[256];
313     MP_WCHAR                vendorName[256];
314     MP_UINT32		    proprietaryPropertyCount;
315     MP_PROPRIETARY_PROPERTY proprietaryProperties[8];
316 
317 } MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES;
318 
319 /**
320  *******************************************************************************
321  *
322  * Declaration of the MP_UINT32 MP_LOGICAL_UNIT_NAME_TYPE constants
323  *
324  *******************************************************************************
325  */
326 #define MP_LU_NAME_TYPE_UNKNOWN         0
327 #define MP_LU_NAME_TYPE_VPD83_TYPE1     1
328 #define MP_LU_NAME_TYPE_VPD83_TYPE2     2
329 #define MP_LU_NAME_TYPE_VPD83_TYPE3     3
330 #define MP_LU_NAME_TYPE_DEVICE_SPECIFIC 4
331 
332 typedef MP_UINT32 MP_LOGICAL_UNIT_NAME_TYPE;
333 
334 /**
335  *******************************************************************************
336  *
337  * Declaration of the MP_UINT32 MP_AUTOFAILBACK_SUPPORT constants
338  *
339  *******************************************************************************
340  */
341 #define MP_AUTOFAILBACK_SUPPORT_NONE	0
342 #define MP_AUTOFAILBACK_SUPPORT_PLUGIN	1
343 #define MP_AUTOFAILBACK_SUPPORT_MPLU	2
344 #define MP_AUTOFAILBACK_SUPPORT_PLUGINANDMPLU	3
345 
346 typedef MP_UINT32 MP_AUTOFAILBACK_SUPPORT;
347 
348 /**
349  *******************************************************************************
350  *
351  * Declaration of the MP_UINT32 MP_AUTOPROBING_SUPPORT constants
352  *
353  *******************************************************************************
354  */
355 #define MP_AUTOPROBING_SUPPORT_NONE	0
356 #define MP_AUTOPROBING_SUPPORT_PLUGIN	1
357 #define MP_AUTORPOBING_SUPPORT_MPLU	2
358 #define MP_AUTORPOBING_SUPPORT_PLUGINANDMPLU	3
359 
360 typedef MP_UINT32 MP_AUTOPROBING_SUPPORT;
361 
362 /**
363  *******************************************************************************
364  *
365  * Declaration of the MP_OID structure
366  *
367  * This structure should be treated as opaque by clients of the API.
368  * Appropriate APIs should be used to extract information from the structure.
369  *
370  * Also ZERO_OID is defined for APIs that may handle multiple plugin OIDs.
371  *
372  *******************************************************************************
373  */
374 typedef struct _MP_OID
375 {
376     /**
377      * The type of the object.  When an object ID is supplied as a parameter
378      * to an API the library uses this value to insure that the supplied
379      * object ID's type is appropriate for the API.
380      */
381     MP_OBJECT_TYPE objectType;
382 
383     /**
384      * A value determined by the library which it uses to uniquely identify the
385      * owner of an object.  The owner of an object is either the library itself
386      * or a plugin.  When an object ID is supplied as a parameter to an API the
387      * library uses this value to determine if it should handle the call itself
388      * or direct the call to one or more plugins.
389      */
390     MP_UINT32      ownerId;
391 
392     /**
393      * A value determined by a plugin which a plugin uses, perhaps in
394      * combination with the object type, to uniquely identify one of its
395      * objects.
396      */
397     MP_UINT64      objectSequenceNumber;
398 
399 } MP_OID;
400 
401 #define ZERO_OID ((const MP_OID){MP_OBJECT_TYPE_UNKNOWN,0,0})
402 
403 /**
404  *******************************************************************************
405  *
406  * Declaration of the MP_OID_LIST structure
407  *
408  * This structure is used by a number of APIs to return lists of objects.  Any
409  * instance of this structure returned by an API must be freed by a client
410  * using the MP_FreeOidList API.  Although oids is declared to be an
411  * array of one
412  * @ref MP_OID structure it can in fact contain any number of
413  * @ref MP_OID structures.  The oidCount indicates the number of @ref MP_OID
414  * structures in the oids array.
415  *
416  * @note The @a oids array is a variable length array, despite its declaration
417  *       below it can be of any length.
418  *
419  *******************************************************************************
420  */
421 typedef struct _MP_OID_LIST
422 {
423     /**
424      * The number of object IDs in the @a oids array.
425      */
426     MP_UINT32       oidCount;
427 
428     /**
429      * A variable length array of zero or more object IDs.  There are
430      * 'oidCount' object IDs in this array.
431      */
432     MP_OID         oids[1];
433 
434 } MP_OID_LIST;
435 
436 /**
437  *******************************************************************************
438  *
439  * Declaration of the MP_LIBRARY_PROPERTIES structure
440  *
441  * This structure is returned by the MP_GetLibraryProperties() API.
442  *
443  *******************************************************************************
444  */
445 typedef struct _MP_LIBRARY_PROPERTIES
446 {
447     /**
448      * The version of the Multipath Management API implemented by the library.
449      */
450     MP_UINT32       supportedMpVersion;
451 
452     /**
453      * A null terminated ASCII string containing the name of the vendor that
454      * created the binary version of the library.
455      */
456     MP_WCHAR        vendor[256];
457 
458     /**
459      * A null terminated ASCII string containing the implementation version
460      * of the library from the vendor specified in the 'vendor' field.
461      */
462     MP_WCHAR        implementationVersion[256];
463 
464     /**
465      * A null terminated ASCII string ideally containing the path and file
466      * name of the library that is being used by the currently executing
467      * process can be found. If the path cannot be determined then it is
468      * acceptable to fill this field with only the name (and extension if
469      * applicable) of the file of the library.  If this cannot be determined
470      * then this field should be an empty string.
471      */
472     MP_CHAR        fileName[256];
473 
474     /**
475      * The time and date that the library that is executing was built.
476      */
477     MP_WCHAR        buildTime[256];
478 
479 } MP_LIBRARY_PROPERTIES;
480 
481 /**
482  *******************************************************************************
483  *
484  * Declaration of the MP_PLUGIN_PROPERTIES structure
485  *
486  * This structure is returned by the MP_GetPluginProperties() API.
487  *
488  *******************************************************************************
489  */
490 typedef struct _MP_PLUGIN_PROPERTIES
491 {
492     /**
493      * The version of the Multipath Management API implemented by a plugin.
494      */
495     MP_UINT32 supportedMpVersion;
496 
497     /**
498      * A null terminated Unicode string containing the name of the vendor that
499      * created the binary version of the plugin.
500      */
501     MP_WCHAR vendor[256];
502 
503     /**
504      * A null terminated Unicode string containing the implementation version
505      * of the plugin from the vendor specified in vendor.
506      */
507     MP_WCHAR implementationVersion[256];
508 
509     /**
510      * A null terminated ASCII string ideally containing the path and file
511      * name of the plugin that is filling in this structure.
512      */
513     MP_CHAR fileName[256];
514 
515     /**
516      * The time and date that the plugin that is executing was built.
517      */
518     MP_WCHAR buildTime[256];
519 
520     /**
521      * A null terminated Unicode string containing the name of the multipath
522      * driver vendor associated with this plugin.
523      */
524     MP_WCHAR driverVendor[256];
525 
526     /**
527      * A null terminated Unicode string ideally containing the path and file
528      * name of the plugin that is filling in this structure.
529      */
530     MP_CHAR driverName[256];
531 
532     /**
533      * A null terminated Unicode string containing the version number of
534      * the multipath driver.
535      */
536     MP_WCHAR driverVersion[256];
537 
538     /**
539      * A set of flags representing the load balance types
540      * (MP_LOAD_BALANCE_TYPES) supported by the plugin/driver as a plugin-wide
541      * property.
542      */
543     MP_UINT32 supportedLoadBalanceTypes;
544 
545     /**
546      * boolean indicating whether the implementation supports activating target
547      * port groups.
548      */
549     MP_BOOL canSetTPGAccess;
550 
551     /**
552      * A Boolean indicating whether the implementations supports overriding
553      * paths. Setting this to true indicates MP_SetOverridePath and
554      * MP_CancelOverridePath are supported.
555      */
556     MP_BOOL canOverridePaths;
557 
558     /**
559      * A boolean indicating whether the implementation exposes (or leaves
560      * exposed) device files for the individual paths encapsulated by the
561      * multipath device file. This is typically true for MP drivers that sit
562      * near the top of the driver stack..
563      */
564     MP_BOOL exposesPathDeviceFiles;
565 
566     /**
567      * A string representing the primary file names the driver uses for
568      * multipath logical units.
569      */
570     MP_CHAR deviceFileNamespace[256];
571 
572     /**
573      * A boolean indicating whether the driver limits multipath capabilities
574      * to certain device types. If true, then the driver only provides multipath
575      * support to devices exposed through MP_DEVICE_PRODUCT_PROPERTIES
576      * instances. If false, then the driver supports any device that provides
577      * standard SCSI logical unit identifiers.
578      */
579     MP_BOOL onlySupportsSpecifiedProducts;
580 
581     /**
582      * Describes the range of administer settable path weights supported by the
583      * driver. A driver with no path preference capabilities should set
584      * this property to zero. A driver with the ability to enable/disable
585      * paths should set this property to 1. Drivers with more weight settings
586      * can set the property appropriately.
587      */
588     MP_UINT32 maximumWeight;
589 
590     /**
591      * The autofailback support indicates whether the implementation supports
592      * auto-failback (to reenable paths that revert to a good state) at the
593      * plugin level, the multipath logical unit level, both levels or whether
594      * auto-failback is unsupported.
595      */
596     MP_AUTOFAILBACK_SUPPORT autoFailbackSupport;
597 
598     /**
599      * A Boolean indicating whether plugin-wide autofailback is currently
600      * enabled. This parameter is undefined if autoFailbackSupport is
601      * MP_AUTOFAILBACK_SUPPORT_NONE or MP_AUTOFAILBACK_SUPPORT_MPLU.
602      */
603     MP_BOOL pluginAutoFailbackEnabled;
604 
605     /**
606      * The maximum plugin-wide polling rate (in seconds) for auto-failback
607      * supported by the driver. A value of zero indicates the driver/plugin
608      * does not support polling. Undefined if autoFailbackSupport is
609      * MP_AUTOFAILBACK_SUPPORT_NONE or MP_AUTOFAILBACK_SUPPORT_MPLU. If the
610      * plugin/driver supports auto-failback without polling or does not provide
611      * a way to set the polling rate, then this must be set to zero (0).
612      * This value is set by the plugin and cannot be modified by users.
613      */
614     MP_UINT32 failbackPollingRateMax;
615 
616     /**
617      * The current plugin-wide auto-failback polling rate (in seconds).
618      * Undefined if autofailbackSupport is MP_AUTOFAILBACK_SUPPORT_NONE or
619      * MP_AUTOFAILBACK_SUPPORT_MPLU. Cannot be more that plooingRateMax.
620      */
621     MP_UINT32 currentFailbackPollingRate;
622 
623     /**
624      * An enumerated type indicating whether the implementation supports
625      * auto-probing at the plugin level, the multipath logical unit level, both
626      * levels or whether auto-probing is unsupported.
627      */
628     MP_AUTOPROBING_SUPPORT autoProbingSupport;
629 
630     /**
631      * A boolean indicating that plugin-wide auto-probing is enabled. This
632      * property is undefined if autoProbingSupport is
633      * MP_AUTOPROBING_SUPPORT_NONE or MP_AUTOPROBING_SUPPORT_MPLU.
634      */
635     MP_BOOL pluginAutoProbingEnabled;
636 
637     /**
638      * The maximum plugin-wide polling rate (in seconds) for auto-probing
639      * supported by the driver. Undefined if autoProbingSupport is
640      * MP_AUTOPROBING_SUPPORT_NONE or MP_AUTOPROBING_SUPPORT_MPLU. If the
641      * plugin/driver supports auto-probing without polling or does not provide a
642      * way to set the probing polling rate, then this must be set to zero (0).
643      * This value is set by the plugin and cannot be modified by users.
644      */
645     MP_UINT32 probingPollingRateMax;
646 
647     /**
648      * The current plugin-wide auto-probing polling rate (in seconds).
649      * Undefined if autoProbingSupport is MP_AUTOPROBING_SUPPORT_NONE or
650      * MP_AUTOPROBING_SUPPORT_MPLU. Cannot be more that probingPollingRateMax.
651      */
652     MP_UINT32 currentProbingPollingRate;
653 
654     /**
655      * The load balance type that will be used by the driver for devices
656      * (without a corresponding MP_DEVICE_PRODUCT_PROPERTIES instance) unless
657      * overridden by the administrator. Any logical unit with vendor, product,
658      * and revision properties matching a MP_DEVICE_PRODUCT_PROPERTIES instance
659      * will default to a device-specific load balance type.
660      */
661     MP_LOAD_BALANCE_TYPE defaultloadBalanceType;
662 
663     /**
664      * The count of proprietary properties (less that or equal to eight)
665      * supported.
666      */
667     MP_UINT32	proprietaryPropertyCount;
668 
669     /**
670      * A list of proprietary property name/value pairs.
671      */
672     MP_PROPRIETARY_PROPERTY proprietaryProperties[8];
673 
674 } MP_PLUGIN_PROPERTIES;
675 
676 /**
677  *******************************************************************************
678  *
679  * Declaration of the MP_DEVICE_PRODUCT_PROPERTIES structure.
680  *
681  * This structure is returned by the MP_GetDeviceProductProperties() API.
682  *
683  *******************************************************************************
684  */
685 typedef struct _MP_DEVICE_PRODUCT_PROPERTIES
686 {
687     MP_CHAR	    vendor[8];
688     MP_CHAR	    product[16];
689     MP_CHAR	    revision[4];
690     MP_UINT32	    supportedLoadBalanceTypes;
691 
692 } MP_DEVICE_PRODUCT_PROPERTIES;
693 
694 /**
695  *******************************************************************************
696  *
697  * Declaration of the MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES structure.
698  *
699  * This structure is returned by the MP_GetMPLogicalUnitProperties() API.
700  *
701  *******************************************************************************
702  */
703 typedef struct _MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES
704 {
705     MP_CHAR			vendor[8];
706     MP_CHAR			product[16];
707     MP_CHAR			revision[4];
708     MP_CHAR			name[256];
709     MP_LOGICAL_UNIT_NAME_TYPE   nameType;
710     MP_CHAR			deviceFileName[256];
711     MP_BOOL			asymmetric;
712     MP_OID			overridePath;
713     MP_LOAD_BALANCE_TYPE	currentLoadBalanceType;
714     MP_UINT32			logicalUnitGroupID;
715     MP_XBOOL			autoFailbackEnabled;
716     MP_UINT32			failbackPollingRateMax;
717     MP_UINT32			currentFailbackPollingRate;
718     MP_XBOOL 			autoProbingEnabled;
719     MP_UINT32 			probingPollingRateMax;
720     MP_UINT32 			currentProbingPollingRate;
721     MP_UINT32 			proprietaryPropertyCount;
722     MP_PROPRIETARY_PROPERTY 	proprietaryProperties[8];
723 
724 } MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES;
725 
726 /**
727  *******************************************************************************
728  *
729  * Declaration of the MP_PATH_LOGICAL_UNIT_PROPERTIES structure.
730  *
731  * This structure is returned by the MP_GetPathLogicalUnitProperties() API.
732  *
733  *******************************************************************************
734  */
735 typedef struct _MP_PATH_LOGICAL_UNIT_PROPERTIES
736 {
737     MP_UINT32	    weight;
738     MP_PATH_STATE   pathState;
739     MP_BOOL	    disabled;
740     MP_OID	    initiatorPortOid;
741     MP_OID	    targetPortOid;
742     MP_OID	    logicalUnitOid;
743     MP_UINT64	    logicalUnitNumber;
744     MP_CHAR	    deviceFileName[256];
745     MP_UINT32	    busNumber;
746     MP_UINT32	    portNumber;
747 
748 } MP_PATH_LOGICAL_UNIT_PROPERTIES;
749 
750 /**
751  *******************************************************************************
752  *
753  * Declaration of the MP_INITIATOR_PORT_PROPERTIES structure.
754  *
755  * This structure is returned by the MP_GetInitiatorPortProperties() API.
756  *
757  *******************************************************************************
758  */
759 typedef struct _MP_INITIATOR_PORT_PROPERTIES
760 {
761     MP_CHAR		    portID[256];
762     MP_PORT_TRANSPORT_TYPE  portType;
763     MP_CHAR		    osDeviceFile[256];
764     MP_WCHAR		    osFriendlyName[256];
765 
766 } MP_INITIATOR_PORT_PROPERTIES;
767 
768 /**
769  *******************************************************************************
770  *
771  * Declaration of the MP_TARGET_PORT_PROPERTIES structure.
772  *
773  * This structure is returned by the MP_GetTargetPortProperties() API.
774  *
775  *******************************************************************************
776  */
777 typedef struct _MP_TARGET_PORT_PROPERTIES
778 {
779     MP_CHAR	portID[256];
780     MP_UINT32	relativePortID;
781 
782 } MP_TARGET_PORT_PROPERTIES;
783 
784 /**
785  *******************************************************************************
786  *
787  * Declaration of the MP_TARGET_PORT_GROUP_PROPERTIES structure.
788  *
789  * This structure is returned by the MP_GetTargetPortGroupProperties() API.
790  *
791  *******************************************************************************
792  */
793 typedef struct _MP_TARGET_PORT_GROUP_PROPERTIES
794 {
795     MP_ACCESS_STATE_TYPE    accessState;
796     MP_BOOL                 explicitFailover;
797     MP_BOOL                 supportsLuAssignment;
798     MP_BOOL		    preferredLuPath;
799     MP_UINT32		    tpgID;
800 
801 } MP_TARGET_PORT_GROUP_PROPERTIES;
802 
803 /**
804  *******************************************************************************
805  *
806  * Declaration of the MP_TPG_STATE_PAIR structure.
807  *
808  * This structure is used as an argument for the MP_SetTPGAcess() API.
809  *
810  *******************************************************************************
811  */
812 typedef struct _MP_TPG_STATE_PAIR
813 {
814     MP_OID                  tpgOid;
815     MP_ACCESS_STATE_TYPE    desiredState;
816 
817 } MP_TPG_STATE_PAIR;
818 
819 /**
820  *******************************************************************************
821  *
822  * Declaration of call back function type for event support
823  *
824  *******************************************************************************
825  */
826 typedef void (* MP_OBJECT_PROPERTY_FN) (
827     MP_OID_LIST *pOidList, void *pCallerData
828 );
829 
830 typedef void (* MP_OBJECT_VISIBILITY_FN) (
831     MP_BOOL becomingVisible, MP_OID_LIST *pOidList, void *pCallerData
832 );
833 
834 void InitLibrary();
835 void ExitLibrary();
836 
837 /**
838  ******************************************************************************
839  *
840  * The APIs for property and object related discovery.
841  *
842  * - MP_GetLibraryProperties
843  * - MP_GetPluginOidList
844  * - MP_GetPluginProperties
845  * - MP_GetAssociatedPluginOid
846  * - MP_GetObjectType
847  * - MP_GetDeviceProductOidList
848  * - MP_GetDeviceProductProperties
849  * - MP_GetInitiatorPortOidList
850  * - MP_GetInitiatorPortProperties
851  * - MP_GetMultipathLus
852  * - MP_GetMPLogicalUnitProperties
853  * - MP_GetAssociatedPathOidList
854  * - MP_GetPathLogicalUnitProperties
855  * - MP_GetAssociatedTPGOidList
856  * - MP_GetTargetPortGroupProperties
857  * - MP_GetMPLuOidListFromTPG
858  * - MP_GetProprietaryLoadBalanceOidList
859  * - MP_GetProprietaryLoadBalanceProperties
860  * - MP_GetTargetPortOidList
861  * - MP_GetTargetPortProperties
862  *
863  ******************************************************************************
864  */
865 
866 /**
867  *******************************************************************************
868  *
869  * Gets the properties of the MP API library that is being used.
870  *
871  * @param  pProps
872  *         A pointer to an MP_LIBRARY_PROPERTIES structure allocated by
873  *         the caller.  On successful return this structure will contain the
874  *         properties of the MP API library.
875  *
876  * @return An MP_STATUS indicating if the operation was successful or if
877  *         an error occurred.
878  *
879  * @retval MP_STATUS_SUCCESS
880  *          Returned if the library properties were successfully returned.
881  *
882  * @retval MP_STATUS_INVALID_PARAMETER
883  *      Returned if ppList pointer passed as placeholder for holding the
884  *      library properties is found to be invalid.
885  *
886  * @retval MP_STATUS_UNSUPPORTED
887  *      Returned when the implementation does not support the API.
888  *
889  ******************************************************************************
890  */
891 MP_STATUS MP_GetLibraryProperties(
892         MP_LIBRARY_PROPERTIES *pProps
893 );
894 
895 /**
896  ******************************************************************************
897  *
898  * Gets a list of the object IDs of all currently loaded plugins.
899  *
900  * @param ppList
901  *        A pointer to a pointer to an MP_OID_LIST.  On successful
902  *        return this will contain a pointer to an @ref MP_OID_LIST
903  *        which contains the object IDs of all of the plugins currently
904  *        loaded by the library.
905  *
906  * @return MP_STATUS indicating if the operation was successful or
907  *          if an error occurred.
908  *
909  * @retval MP_STATUS_INVALID_OBJECT_TYPE
910  *      Returned if oid does not specify any valid object type. This is
911  *      most likely to happen if an uninitialized object ID is passed to
912  *      the API.
913  *
914  * @retval MP_STATUS_INVALID_PARAMETER
915  *      Returned if ppList is NULL or specifies a memory area to which data
916  *      cannot be written. MP_STATUS_SUCCESS Returned when the operation is
917  *      successful.
918  *
919  * @retval MP_STATUS_INSUFFICIENT_MEMORY
920  *      Returned when memory allocation failure occurs*
921  *
922  * @retval MP_STATUS_SUCCESS
923  *          Returned if the plugin ID list was successfully returned.
924  *
925  ******************************************************************************
926  */
927 MP_STATUS MP_GetPluginOidList(
928         MP_OID_LIST **ppList
929 );
930 
931 /**
932  *******************************************************************************
933  *
934  * Gets the properties of the specified vendor plugin.
935  *
936  * @param  oid
937  *         The ID of the plugin whose properties are being retrieved.
938  *
939  * @param  pProps
940  *         A pointer to an @ref MP_PLUGIN_PROPERTIES structure allocated by
941  *         the caller.  On successful return this will contain the properties
942  *         of the plugin specified by pluginOid.
943  *
944  * @return An MP_STATUS indicating if the operation was successful or if an
945  *         error occurred.
946  *
947  * @retval MP_STATUS_SUCCESS
948  *         Returned if the plugin properties were successfully returned.
949  *
950  * @retval MP_STATUS_INVALID_OBJECT_TYPE
951  *         Returned if oid does not specify any valid object type.
952  *
953  * @retval MP_STATUS_OBJECT_NOT_FOUND
954  *         Returned if oid has an owner that is not currently known to
955  *     the system.
956  *
957  * @retval MP_STATUS_INVALID_PARAMETER
958  *         Returned if 'pProps' is NULL or specifies a memory area to
959  *         which data cannot be written.
960  *
961  *******************************************************************************
962  */
963 MP_STATUS MP_GetPluginProperties(
964         MP_OID                oid,
965         MP_PLUGIN_PROPERTIES *pProps
966 );
967 
968 
969 /**
970  *******************************************************************************
971  *
972  * Gets the object ID for the plugin associated with the specified object ID.
973  *
974  * @param  oid
975  *         The object ID of an object that has been received from a previous
976  *         library call.
977  *
978  * @param  pPluginOid
979  *         A pointer to an MP_OID structure allocated by the caller.  On
980  *         successful return this will contain the object ID of the plugin
981  *         associated with the object specified by @a objectId.
982  *
983  * @return An MP_STATUS indicating if the operation was successful or if
984  *         an error occurred.
985  *
986  * @retval MP_STATUS_SUCCESS
987  *          Returned if the associated plugin ID was successfully returned.
988  *
989  * @retval MP_STATUS_OBJECT_NOT_FOUND
990  *          Returned if oid does not specify a plugin that is currently known to
991  *     the system.
992  *
993  * @retval MP_STATUS_INVALID_PARAMETER
994  *          Returned if 'oid' specifies an object not owned by a plugin or
995  *     	    if pPluginOid is NULL or specifies a memory area to which data
996  *          cannot be written.
997  *
998  * @retval MP_STATUS_INVALID_OBJECT_TYPE
999  *          Returned if 'oid' specifies an object with an invalid type.
1000  *
1001  *******************************************************************************
1002  */
1003 MP_STATUS MP_GetAssociatedPluginOid(
1004         MP_OID  oid,
1005         MP_OID *pPluginOid
1006 );
1007 
1008 
1009 /**
1010  *******************************************************************************
1011  *
1012  * Gets the object type of an initialized object ID.
1013  *
1014  * @param  oid
1015  *         The object ID of an object that has been received from a previous
1016  *         library call.
1017  *
1018  * @param  pObjectType
1019  *         A pointer to an MP_OBJECT_TYPE variable allocated by the caller.
1020  *         On successful return this will contain the object type of oid.
1021  *
1022  * @return An MP_STATUS indicating if the operation was successful or
1023  *         if an error occurred.
1024  *
1025  * @retval MP_STATUS_OBJECT_NOT_FOUND
1026  *      Returned if oid has an owner that is not currently known to
1027  *      the system.
1028  *
1029  * @retval MP_STATUS_INVALID_PARAMETER
1030  *      Returned if oid does not specify any valid object type.
1031  *
1032  * @retval MP_STATUS_SUCCESS
1033  *         Returned when the operation is successful.
1034  *
1035  *******************************************************************************
1036  */
1037 MP_STATUS MP_GetObjectType(
1038         MP_OID          oid,
1039         MP_OBJECT_TYPE *pObjectType
1040 );
1041 
1042 
1043 /**
1044  *******************************************************************************
1045  *
1046  * Gets a list of the object IDs of all the device product properties
1047  *       associated with this plugin.
1048  *
1049  * @param  oid
1050  *         The object ID of plugin.
1051  *
1052  * @param  ppList
1053  *      A pointer to a pointer to an MP_OID_LIST structure.
1054  *      On a successful return, this will contain a pointer to
1055  *      an MP_OID_LIST that contains the object IDs of all the device
1056  *      product descriptors associated with the specified plugin.
1057  *
1058  * @return An MP_STATUS indicating if the operation was successful or if
1059  *         an error occurred.
1060  *
1061  * @retval MP_STATUS_SUCCESS
1062  *         Returned when the operation is successful.
1063  *
1064  * @retval MP_STATUS_INVALID_PARAMETER
1065  *      Returned if ppList pointer passed as placeholder for holding
1066  *      the device product list is found to be invalid.
1067  *
1068  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1069  *         Returned if oid does not specify any valid object type.
1070  *
1071  * @retval MP_STATUS_FAILED
1072  *         Returned when the plugin for the specified oid is not found.
1073  *
1074  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1075  *      Returned when memory allocation failure occurs
1076  *
1077  * @retval MP_STATUS_UNSUPPORTED
1078  *      Returned when the API is not supported.
1079  *
1080  *******************************************************************************
1081  */
1082 MP_STATUS MP_GetDeviceProductOidList(
1083         MP_OID        oid,
1084         MP_OID_LIST **ppList
1085 );
1086 
1087 /**
1088  *******************************************************************************
1089  *
1090  * Gets the device product properties of the specified plugin oid.
1091  *
1092  * @param  oid
1093  *         The object ID of the plugin.
1094  *
1095  * @param  ppProps
1096  *      A pointer to an MP_DEVICE_PRODUCT_PROPERTIES structure
1097  *      allocated by the caller. On successful return it will contain
1098  *      a pointer to an MP_DEVICE_PRODUCT_PROPERTIES structure allocated
1099  *      by the library.
1100  *
1101  * @return An MP_STATUS indicating if the operation was successful or if
1102  *         an error occurred.
1103  *
1104  * @retval MP_STATUS_SUCCESS
1105  *         Returned when the operation is successful.
1106  *
1107  * @retval MP_STATUS_INVALID_PARAMETER
1108  *      Returned if ppProps pointer passed as placeholder for holding
1109  *      the device product properties is found to be invalid.
1110  *
1111  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1112  *         Returned if oid does not specify any valid object type.
1113  *
1114  * @retval MP_STATUS_FAILED
1115  *         Returned when the plugin for the specified oid is not found.
1116  *
1117  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1118  *      Returned when memory allocation failure occurs
1119  *
1120  * @retval MP_STATUS_UNSUPPORTED
1121  *      Returned when the API is not supported.
1122  *
1123  *******************************************************************************
1124  */
1125 MP_STATUS MP_GetDeviceProductProperties(
1126         MP_OID                         oid,
1127         MP_DEVICE_PRODUCT_PROPERTIES *pProps
1128 );
1129 
1130 /**
1131  *******************************************************************************
1132  *
1133  * Gets a list of the object IDs of all the initiator ports associated
1134  * with this plugin.
1135  *
1136  * @param  oid
1137  *         The object ID of plugin.
1138  *
1139  * @param  ppList
1140  *      A pointer to a pointer to an MP_OID_LIST structure.
1141  *      On a successful return, this will contain a pointer to
1142  *      an MP_OID_LIST that contains the object IDs of all the initiator
1143  *      ports associated with the specified plugin.
1144  *
1145  * @return An MP_STATUS indicating if the operation was successful or if
1146  *         an error occurred.
1147  *
1148  * @retval MP_STATUS_SUCCESS
1149  *         Returned when the operation is successful.
1150  *
1151  * @retval MP_STATUS_INVALID_PARAMETER
1152  *      Returned if ppList pointer passed as placeholder for holding
1153  *      the initiator port list is found to be invalid.
1154  *
1155  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1156  *          Returned if oid does not specify any valid object type.
1157  *
1158  * @retval MP_STATUS_FAILED
1159  *          Returned when the plugin for the specified oid is not found.
1160  *
1161  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1162  *      Returned when memory allocation failure occurs
1163  *
1164  * @retval MP_STATUS_UNSUPPORTED
1165  *      Returned when the API is not supported.
1166  *
1167  *******************************************************************************
1168  */
1169 MP_STATUS MP_GetInitiatorPortOidList(
1170         MP_OID        oid,
1171         MP_OID_LIST **ppList
1172 );
1173 
1174 /**
1175  *******************************************************************************
1176  *
1177  * Gets the properties of the specified initiator port.
1178  *
1179  * @param  oid
1180  *         The object ID of the initiator port.
1181  *
1182  * @param  pProps
1183  *      A pointer to an MP_INITIATOR_PORT_PROPERTIES structure
1184  *      allocated by the caller. On successful return, this structure
1185  *      will contain the properties of the port specified by oid.
1186  *
1187  * @return An MP_STATUS indicating if the operation was successful or if
1188  *         an error occurred.
1189  *
1190  * @retval MP_STATUS_SUCCESS
1191  *         Returned when the operation is successful.
1192  *
1193  * @retval MP_STATUS_INVALID_PARAMETER
1194  *      Returned if pProps is NULL or specifies a memory area to
1195  *      which data cannot be written.
1196  *
1197  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1198  *          Returned if oid does not specify any valid object type.
1199  *
1200  * @retval MP_STATUS_OBJECT_NOT_FOUND
1201  *          Returned if oid has an owner that is not currently known to
1202  *      the system.
1203  *
1204  *******************************************************************************
1205  */
1206 MP_STATUS MP_GetInitiatorPortProperties(
1207         MP_OID                        oid,
1208         MP_INITIATOR_PORT_PROPERTIES *pProps
1209 );
1210 
1211 /**
1212  *******************************************************************************
1213  *
1214  * Gets a list of multipath logical units associated to a plugin.
1215  *
1216  * @param  oid
1217  *         The object ID of plugin.
1218  *
1219  * @param  ppList
1220  *      A pointer to a pointer to an MP_OID_LIST structure.
1221  *      On a successful return, this will contain a pointer to
1222  *      an MP_OID_LIST that contains the object IDs of all the multipath
1223  *      logical units associated with the specified plugin.
1224  *
1225  * @return An MP_STATUS indicating if the operation was successful or if
1226  *         an error occurred.
1227  *
1228  * @retval MP_STATUS_SUCCESS
1229  *         Returned when the operation is successful.
1230  *
1231  * @retval MP_STATUS_INVALID_PARAMETER
1232  *      Returned if ppList pointer passed as placeholder for holding
1233  *      the multipath logical unit list is found to be invalid.
1234  *
1235  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1236  *          Returned if oid does not specify any valid object type.
1237  *
1238  * @retval MP_STATUS_FAILED
1239  *          Returned when the plugin for the specified oid is not found.
1240  *
1241  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1242  *      Returned when memory allocation failure occurs
1243  *
1244  * @retval MP_STATUS_UNSUPPORTED
1245  *      Returned when the API is not supported.
1246  *
1247  *******************************************************************************
1248  */
1249 MP_STATUS MP_GetMultipathLus(
1250         MP_OID        oid,
1251         MP_OID_LIST **ppList
1252 );
1253 
1254 /**
1255  *******************************************************************************
1256  *
1257  * Gets the properties of the specified logical unit.
1258  *
1259  * @param  oid
1260  *         The object ID of the multipath logical unit.
1261  *
1262  * @param  pProps
1263  *      A pointer to an MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES structure
1264  *      allocated by the caller. On successful return, this structure
1265  *      will contain the properties of the port specified by oid.
1266  *
1267  * @return An MP_STATUS indicating if the operation was successful or if
1268  *         an error occurred.
1269  *
1270  * @retval MP_STATUS_SUCCESS
1271  *         Returned when the operation is successful.
1272  *
1273  * @retval MP_STATUS_INVALID_PARAMETER
1274  *      Returned if pProps is NULL or specifies a memory area to
1275  *      which data cannot be written.
1276  *
1277  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1278  *          Returned if oid does not specify any valid object type.
1279  *
1280  * @retval MP_STATUS_OBJECT_NOT_FOUND
1281  *          Returned if oid has an owner that is not currently known to
1282  *      the system.
1283  *
1284  *******************************************************************************
1285  */
1286 MP_STATUS MP_GetMPLogicalUnitProperties(
1287         MP_OID                                oid,
1288         MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES *pProps
1289 );
1290 
1291 /**
1292  *******************************************************************************
1293  *
1294  * Gets a list of the object IDs of all the path logical units associated
1295  * with the specified multipath logical unit, initiator port, or target port.
1296  *
1297  * @param  oid
1298  *         The object ID of multipath logical unit, initiator port, or
1299  *     target port.
1300  *
1301  * @param  ppList
1302  *      A pointer to a pointer to an MP_OID_LIST structure.
1303  *      On a successful return, this will contain a pointer to
1304  *      an MP_OID_LIST that contains the object IDs of all the mp path
1305  *      logical units associated with the specified OID.
1306  *
1307  * @return An MP_STATUS indicating if the operation was successful or if
1308  *         an error occurred.
1309  *
1310  * @retval MP_STATUS_SUCCESS
1311  *         Returned when the operation is successful.
1312  *
1313  * @retval MP_STATUS_INVALID_PARAMETER
1314  *      Returned if ppList pointer passed as placeholder for holding
1315  *      the device product list is found to be invalid.
1316  *
1317  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1318  *          Returned if oid does not specify any valid object type.
1319  *
1320  * @retval MP_STATUS_FAILED
1321  *          Returned when the plugin for the specified oid is not found.
1322  *
1323  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1324  *      Returned when memory allocation failure occurs
1325  *
1326  * @retval MP_STATUS_OBJECT_NOT_FOUND
1327  *      Returned if oid has an owner that is not currently known to
1328  *      the system.
1329  *
1330  *******************************************************************************
1331  */
1332 MP_STATUS MP_GetAssociatedPathOidList(
1333         MP_OID        oid,
1334         MP_OID_LIST **ppList
1335 );
1336 
1337 /**
1338  *******************************************************************************
1339  *
1340  * Gets the properties of the specified path logical unit.
1341  *
1342  * @param  oid
1343  *         The object ID of the path logical unit.
1344  *
1345  * @param  pProps
1346  *      A pointer to an MP_PATH_LOGICAL_UNIT_PROPERTIES structure
1347  *      allocated by the caller. On successful return, this structure
1348  *      will contain the properties of the port specified by oid.
1349  *
1350  * @return An MP_STATUS indicating if the operation was successful or if
1351  *         an error occurred.
1352  *
1353  * @retval MP_STATUS_SUCCESS
1354  *         Returned when the operation is successful.
1355  *
1356  * @retval MP_STATUS_INVALID_PARAMETER
1357  *      Returned if pProps is NULL or specifies a memory area to
1358  *      which data cannot be written.
1359  *
1360  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1361  *          Returned if oid does not specify any valid object type.
1362  *
1363  * @retval MP_STATUS_OBJECT_NOT_FOUND
1364  *          Returned if oid has an owner that is not currently known to
1365  *      the system.
1366  *
1367  *******************************************************************************
1368  */
1369 MP_STATUS MP_GetPathLogicalUnitProperties(
1370         MP_OID                           oid,
1371         MP_PATH_LOGICAL_UNIT_PROPERTIES *pProps
1372 );
1373 
1374 /**
1375  *******************************************************************************
1376  *
1377  * Gets a list of the object IDs of all the target port group associated
1378  * with the specified multipath logical unit.
1379  *
1380  * @param  oid
1381  *         The object ID of the multiple logical unit.
1382  *
1383  * @param  ppList
1384  *      A pointer to a pointer to an MP_OID_LIST structure.
1385  *      On a successful return, this will contain a pointer to
1386  *      an MP_OID_LIST that contains the object IDs of all the target
1387  *      port group associated with the specified multipath logical unit.
1388  *
1389  * @return An MP_STATUS indicating if the operation was successful or if
1390  *         an error occurred.
1391  *
1392  * @retval MP_STATUS_SUCCESS
1393  *         Returned when the operation is successful.
1394  *
1395  * @retval MP_STATUS_INVALID_PARAMETER
1396  *      Returned if ppList pointer passed as placeholder for holding
1397  *      the target port group list is found to be invalid.
1398  *
1399  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1400  *          Returned if oid does not specify any valid object type.
1401  *
1402  * @retval MP_STATUS_FAILED
1403  *          Returned when the plugin for the specified oid is not found.
1404  *
1405  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1406  *      Returned when memory allocation failure occurs
1407  *
1408  *
1409  *******************************************************************************
1410  */
1411 MP_STATUS MP_GetAssociatedTPGOidList(
1412         MP_OID        oid,
1413         MP_OID_LIST **ppList
1414 );
1415 
1416 /**
1417  *******************************************************************************
1418  *
1419  * Gets the properties of the specified target port group.
1420  *
1421  * @param  oid
1422  *         The object ID of the target port group.
1423  *
1424  * @param  pProps
1425  *      A pointer to an MP_TARGET_PORT_GROUP_PROPERTIES structure
1426  *      allocated by the caller. On successful return, this structure
1427  *      will contain the properties of the port specified by oid.
1428  *
1429  * @return An MP_STATUS indicating if the operation was successful or if
1430  *         an error occurred.
1431  *
1432  * @retval MP_STATUS_SUCCESS
1433  *         Returned when the operation is successful.
1434  *
1435  * @retval MP_STATUS_INVALID_PARAMETER
1436  *      Returned if pProps is NULL or specifies a memory area to
1437  *      which data cannot be written.
1438  *
1439  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1440  *          Returned if oid does not specify any valid object type.
1441  *
1442  * @retval MP_STATUS_OBJECT_NOT_FOUND
1443  *          Returned if oid has an owner that is not currently known to
1444  *      the system.
1445  *
1446  *******************************************************************************
1447  */
1448 MP_STATUS MP_GetTargetPortGroupProperties(
1449         MP_OID                           oid,
1450         MP_TARGET_PORT_GROUP_PROPERTIES *pProps
1451 );
1452 
1453 /**
1454  *******************************************************************************
1455  *
1456  * Gets a list of multipath logical units associated with the specific target
1457  *  port group.
1458  *
1459  * @param  oid
1460  *         The object ID of the target port group.
1461  *
1462  * @param  ppList
1463  *      A pointer to a pointer to an MP_OID_LIST structure.
1464  *      On a successful return, this will contain a pointer to
1465  *      an MP_OID_LIST that contains the object IDs of all the multipath
1466  *      logical units associated with the specified target port group.
1467  *
1468  * @return An MP_STATUS indicating if the operation was successful or if
1469  *         an error occurred.
1470  *
1471  * @retval MP_STATUS_SUCCESS
1472  *         Returned when the operation is successful.
1473  *
1474  * @retval MP_STATUS_INVALID_PARAMETER
1475  *      Returned if ppList pointer passed as placeholder for holding
1476  *      the multipath logical unit list is found to be invalid.
1477  *
1478  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1479  *          Returned if oid does not specify any valid object type.
1480  *
1481  * @retval MP_STATUS_FAILED
1482  *          Returned when the plugin for the specified oid is not found.
1483  *
1484  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1485  *      Returned when memory allocation failure occurs
1486  *
1487  *******************************************************************************
1488  */
1489 MP_STATUS MP_GetMPLuOidListFromTPG(
1490         MP_OID        oid,
1491         MP_OID_LIST **ppList
1492 );
1493 
1494 /**
1495  *******************************************************************************
1496  *
1497  * Gets a list of the object IDs of all the proprietary load balance
1498  * algorithms associated with this plugin.
1499  *
1500  * @param  oid
1501  *         The object ID of the plugin.
1502  *
1503  * @param  ppList
1504  *      A pointer to a pointer to an MP_OID_LIST structure.
1505  *      On a successful return, this will contain a pointer to
1506  *      an MP_OID_LIST that contains the object IDs of all the proprietary
1507  *      load balance algorithms associated with the specified plugin.
1508  *
1509  * @return An MP_STATUS indicating if the operation was successful or if
1510  *         an error occurred.
1511  *
1512  * @retval MP_STATUS_SUCCESS
1513  *         Returned when the operation is successful.
1514  *
1515  * @retval MP_STATUS_INVALID_PARAMETER
1516  *      Returned if ppList pointer passed as placeholder for holding
1517  *      the proprietary load balance oid list is found to be invalid.
1518  *
1519  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1520  *          Returned if oid does not specify any valid object type.
1521  *
1522  * @retval MP_STATUS_FAILED
1523  *          Returned when the plugin for the specified oid is not found.
1524  *
1525  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1526  *      Returned when memory allocation failure occurs
1527  *
1528  * @retval MP_STATUS_UNSUPPORTED
1529  *      Returned when the API is not supported.
1530  *
1531  *******************************************************************************
1532  */
1533 MP_STATUS MP_GetProprietaryLoadBalanceOidList(
1534         MP_OID        oid,
1535         MP_OID_LIST **ppList
1536 );
1537 
1538 /**
1539  *******************************************************************************
1540  *
1541  * Gets the properties of the specified load balance properties structure.
1542  *
1543  * @param  oid
1544  *         The object ID of the proprietary load balance structure.
1545  *
1546  * @param  pProps
1547  *      A pointer to an MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES structure
1548  *      allocated by the caller. On successful return, this structure
1549  *      will contain the properties of the port specified by oid.
1550  *
1551  * @return An MP_STATUS indicating if the operation was successful or if
1552  *         an error occurred.
1553  *
1554  * @retval MP_STATUS_SUCCESS
1555  *         Returned when the operation is successful.
1556  *
1557  * @retval MP_STATUS_INVALID_PARAMETER
1558  *      Returned if pProps is NULL or specifies a memory area to
1559  *      which data cannot be written.
1560  *
1561  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1562  *      Returned if oid does not specify any valid object type.
1563  *
1564  * @retval MP_STATUS_OBJECT_NOT_FOUND
1565  *      Returned if oid has an owner that is not currently known to
1566  *      the system.
1567  *
1568  *******************************************************************************
1569  */
1570 MP_STATUS MP_GetProprietaryLoadBalanceProperties(
1571         MP_OID                     oid,
1572         MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES *pProps
1573 );
1574 
1575 /**
1576  *******************************************************************************
1577  *
1578  * Gets a list of the object IDs of the target ports in the specified target
1579  * port group.
1580  *
1581  * @param  oid
1582  *         The object ID of the target port group.
1583  *
1584  * @param  ppList
1585  *      A pointer to a pointer to an MP_OID_LIST structure.
1586  *      On a successful return, this will contain a pointer to
1587  *      an MP_OID_LIST that contains the object IDs of all the target ports
1588  *      associated with the specified target port group.
1589  *
1590  * @return An MP_STATUS indicating if the operation was successful or if
1591  *         an error occurred.
1592  *
1593  * @retval MP_STATUS_SUCCESS
1594  *         Returned when the operation is successful.
1595  *
1596  * @retval MP_STATUS_INVALID_PARAMETER
1597  *      Returned if ppList pointer passed as placeholder for holding
1598  *      the multipath logical unit list is found to be invalid.
1599  *
1600  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1601  *          Returned if oid does not specify any valid object type.
1602  *
1603  * @retval MP_STATUS_FAILED
1604  *          Returned when the plugin for the specified oid is not found.
1605  *
1606  * @retval MP_STATUS_INSUFFICIENT_MEMORY
1607  *      Returned when memory allocation failure occurs
1608  *
1609  *******************************************************************************
1610  */
1611 MP_STATUS MP_GetTargetPortOidList(
1612         MP_OID        oid,
1613         MP_OID_LIST **ppList
1614 );
1615 
1616 /**
1617  *******************************************************************************
1618  *
1619  * Gets the properties of the specified target port.
1620  *
1621  * @param  oid
1622  *         The object ID of the target port.
1623  *
1624  * @param  pProps
1625  *      A pointer to an MP_TARGET_PORT_PROPERTIES structure
1626  *      allocated by the caller. On successful return, this structure
1627  *      will contain the properties of the port specified by oid.
1628  *
1629  * @return An MP_STATUS indicating if the operation was successful or if
1630  *         an error occurred.
1631  *
1632  * @retval MP_STATUS_SUCCESS
1633  *         Returned when the operation is successful.
1634  *
1635  * @retval MP_STATUS_INVALID_PARAMETER
1636  *      Returned if pProps is NULL or specifies a memory area to
1637  *      which data cannot be written.
1638  *
1639  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1640  *          Returned if oid does not specify any valid object type.
1641  *
1642  * @retval MP_STATUS_OBJECT_NOT_FOUND
1643  *          Returned if oid has an owner that is not currently known to
1644  *      the system.
1645  *
1646  *******************************************************************************
1647  */
1648 MP_STATUS MP_GetTargetPortProperties(
1649         MP_OID                     oid,
1650         MP_TARGET_PORT_PROPERTIES *pProps
1651 );
1652 
1653 /**
1654  ******************************************************************************
1655  *
1656  * The APIs for path management.
1657  *
1658  * - MP_AssignLogicalUnitToTPG
1659  * - MP_SetOverridePath
1660  * - MP_CancelOverridePath
1661  * - MP_EnableAutoFailback
1662  * - MP_DisableAutoFailback
1663  * - MP_EnableAutoProbing
1664  * - MP_DisableAutoProbing
1665  * - MP_EnablePath
1666  * - MP_DisablePath
1667  * - MP_SetLogicalUnitLoadBalanceType
1668  * - MP_SetPluginLoadBalanceType
1669  * - MP_SetPathWeight
1670  * - MP_SetFailbackPollingRates
1671  * - MP_SetProbingPollingRates
1672  * - MP_SetProprietaryProperties
1673  * - MP_SetTPGAccess
1674  *
1675  ******************************************************************************
1676  */
1677 
1678 /**
1679  *******************************************************************************
1680  *
1681  * Assign a multipath logical unit to a target port group.
1682  *
1683  * @param  tpgOid
1684  *      An MP_TARGET_PORT_GROUP oid. The target port group currently in
1685  *      active access state that the administrator would like the LU
1686  *      assigned to.
1687  *
1688  * @param  luOid
1689  *      An MP_MULTIPATH_LOGICAL_UNIT oid.
1690  *
1691  * @return An MP_STATUS indicating if the operation was successful or if
1692  *         an error occurred.
1693  *
1694  * @retval MP_STATUS_SUCCESS
1695  *         Returned when the operation is successful.
1696  *
1697  * @retval MP_STATUS_INVALID_PARAMETER
1698  *      Returned when luOid is not associated with tpgOid.
1699  *
1700  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1701  *          Returned if oid does not specify any valid object type.
1702  *
1703  * @retval MP_STATUS_OBJECT_NOT_FOUND
1704  *          Returned if oid has an owner that is not currently known to
1705  *      the system.
1706  *
1707  *******************************************************************************
1708  */
1709 MP_STATUS MP_AssignLogicalUnitToTPG(
1710         MP_OID tpgOid,
1711         MP_OID luOid
1712 );
1713 
1714 /**
1715  *******************************************************************************
1716  *
1717  * Manually override the path for a logical unit. The path exclusively used to
1718  * access the logical unit until cleared.
1719  *
1720  * @param  logicalUnitOid
1721  *      The object ID of the multipath logical unit.
1722  *
1723  * @param  pathOid
1724  *      The object ID of the path logical unit.
1725  *
1726  * @return An MP_STATUS indicating if the operation was successful or if
1727  *         an error occurred.
1728  *
1729  * @retval MP_STATUS_SUCCESS
1730  *         Returned when the operation is successful.
1731  *
1732  * @retval MP_STATUS_INVALID_PARAMETER
1733  *      Returned if the oid of the object is not valid
1734  *
1735  * @retval MP_STATUS_UNSUPPORTED
1736  *      Returned when the implementation does not support the API
1737  *
1738  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1739  *          Returned if oid does not specify any valid object type.
1740  *
1741  * @retval MP_STATUS_PATH_NONOPERATIONAL
1742  *          Returned when the driver cannot communicate through selected path.
1743  *
1744  *******************************************************************************
1745  */
1746 MP_STATUS MP_SetOverridePath(
1747     MP_OID logicalUnitOid,
1748     MP_OID pathOid
1749 );
1750 
1751 /**
1752  *******************************************************************************
1753  *
1754  * Cancel a path override and re-enable load balancing.
1755  *
1756  * @param  luOid
1757  *         An MP_MULTIPATH_LOGICAL_UNIT oid.
1758  *
1759  * @return An MP_STATUS indicating if the operation was successful or if
1760  *         an error occurred.
1761  *
1762  * @retval MP_STATUS_SUCCESS
1763  *         Returned when the operation is successful.
1764  *
1765  * @retval MP_STATUS_INVALID_PARAMETER
1766  *      Returned if MP_MULTIPATH_LOGICAL_UNIT with the luOid is not found.
1767  *
1768  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1769  *          Returned if oid does not specify any valid object type.
1770  *
1771  * @retval MP_STATUS_OBJECT_NOT_FOUND
1772  *          Returned if oid has an owner that is not currently known to
1773  *      the system.
1774  *
1775  *******************************************************************************
1776  */
1777 MP_STATUS MP_CancelOverridePath(
1778         MP_OID logicalUnitOid
1779 );
1780 
1781 /**
1782  *******************************************************************************
1783  *
1784  * Enables Auto-failback.
1785  *
1786  * @param  oid
1787  *      The oid of the plugin or the multipath logical unit.
1788  *
1789  * @return An MP_STATUS indicating if the operation was successful or if
1790  *         an error occurred.
1791  *
1792  * @retval MP_STATUS_SUCCESS
1793  *         Returned when the operation is successful.
1794  *
1795  * @retval MP_STATUS_INVALID_PARAMETER
1796  *      Returned if oid is NULL or specifies a memory area that is not
1797  *      a valid plugin oid.
1798  *
1799  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1800  *          Returned if oid does not specify any valid object type.
1801  *
1802  *******************************************************************************
1803  */
1804 MP_STATUS MP_EnableAutoFailback(
1805     MP_OID oid
1806 );
1807 
1808 /**
1809  *******************************************************************************
1810  *
1811  * Disables Auto-failback.
1812  *
1813  * @param  oid
1814  *      The oid of the plugin or the multipath logical unit..
1815  *
1816  * @return An MP_STATUS indicating if the operation was successful or if
1817  *         an error occurred.
1818  *
1819  * @retval MP_STATUS_SUCCESS
1820  *         Returned when the operation is successful.
1821  *
1822  * @retval MP_STATUS_INVALID_PARAMETER
1823  *      Returned if oid is NULL or specifies a memory area that is not
1824  *      a valid plugin oid.
1825  *
1826  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1827  *          Returned if oid does not specify any valid object type.
1828  *
1829  *******************************************************************************
1830  */
1831 MP_STATUS MP_DisableAutoFailback(
1832     MP_OID oid
1833 );
1834 
1835 /**
1836  *******************************************************************************
1837  *
1838  * Enables Auto-probing.
1839  *
1840  * @param  oid
1841  *      The oid of the plugin or the multipath logical unit.
1842  *
1843  * @return An MP_STATUS indicating if the operation was successful or if
1844  *         an error occurred.
1845  *
1846  * @retval MP_STATUS_SUCCESS
1847  *         Returned when the operation is successful.
1848  *
1849  * @retval MP_STATUS_INVALID_PARAMETER
1850  *      Returned if oid is NULL or specifies a memory area that is not
1851  *      a valid plugin oid.
1852  *
1853  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1854  *          Returned if oid does not specify any valid object type.
1855  *
1856  *******************************************************************************
1857  */
1858 MP_STATUS MP_EnableAutoProbing(
1859     MP_OID oid
1860 );
1861 
1862 /**
1863  *******************************************************************************
1864  *
1865  * Disables Auto-probing.
1866  *
1867  * @param  oid
1868  *      The oid of the plugin or the multipath logical unit.
1869  *
1870  * @return An MP_STATUS indicating if the operation was successful or if
1871  *         an error occurred.
1872  *
1873  * @retval MP_STATUS_SUCCESS
1874  *         Returned when the operation is successful.
1875  *
1876  * @retval MP_STATUS_INVALID_PARAMETER
1877  *      Returned if oid is NULL or specifies a memory area that is not
1878  *      a valid plugin oid.
1879  *
1880  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1881  *          Returned if oid does not specify any valid object type.
1882  *
1883  *******************************************************************************
1884  */
1885 MP_STATUS MP_DisableAutoProbing(
1886     MP_OID oid
1887 );
1888 
1889 /**
1890  *******************************************************************************
1891  *
1892  * Enables a path. This API may cause failover in a logical unit with
1893  * asymmetric access.
1894  *
1895  * @param  oid
1896  *      The oid of the path.
1897  *
1898  * @return An MP_STATUS indicating if the operation was successful or if
1899  *         an error occurred.
1900  *
1901  * @retval MP_STATUS_SUCCESS
1902  *         Returned when the operation is successful.
1903  *
1904  * @retval MP_STATUS_INVALID_PARAMETER
1905  *      Returned if oid is NULL or specifies a memory area that is not
1906  *      a valid path oid.
1907  *
1908  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1909  *          Returned if oid does not specify any valid object type.
1910  *
1911  *******************************************************************************
1912  */
1913 MP_STATUS MP_EnablePath(
1914     MP_OID oid
1915 );
1916 
1917 /**
1918  *******************************************************************************
1919  *
1920  * Disables a path. This API may cause failover in a logical unit with
1921  * asymmetric access. This API may cause a logical unit to become unavailable.
1922  *
1923  * @param  oid
1924  *      The oid of the path.
1925  *
1926  * @return An MP_STATUS indicating if the operation was successful or if
1927  *         an error occurred.
1928  *
1929  * @retval MP_STATUS_SUCCESS
1930  *         Returned when the operation is successful.
1931  *
1932  * @retval MP_STATUS_INVALID_PARAMETER
1933  *      Returned if oid is NULL or specifies a memory area that is not
1934  *      a valid path oid.
1935  *
1936  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1937  *          Returned if oid does not specify any valid object type.
1938  *
1939  * @retval MP_STATUS_UNSUPPORTED
1940  *          Returned when the API is not supported.
1941  *
1942  * @retval MP_STATUS_TRY_AGAIN
1943  *          Returned when path cannot be disabled at this time.
1944  *
1945  * @retval MP_STATUS_NOT_PERMITTED
1946  *          Returned when disabling thsi path would cause the login unit to
1947  * 	    become unavailable.
1948  *
1949  *******************************************************************************
1950  */
1951 MP_STATUS MP_DisablePath(
1952     MP_OID oid
1953 );
1954 
1955 /**
1956  *******************************************************************************
1957  *
1958  * Set the multipath logical unit s load balancing policy.
1959  *
1960  * @param  logicalUnitoid
1961  *      The object ID of the multipath logical unit.
1962  *
1963  * @param  loadBanlance
1964  *      The desired load balance policy for the specified logical unit.
1965  *
1966  * @return An MP_STATUS indicating if the operation was successful or if
1967  *         an error occurred.
1968  *
1969  * @retval MP_STATUS_SUCCESS
1970  *         Returned when the operation is successful.
1971  *
1972  * @retval MP_STATUS_INVALID_PARAMETER
1973  *      Returned if no MP_MULTIPATH_LOGICAL_UNIT associated with
1974  *      @ref ligicalUnitrOid is found or invalid MP_LOAD_BALANCE_TYPE is
1975  *      specified.
1976  *
1977  * @retval MP_STATUS_FAILED
1978  *      Returned when the specified loadBalance type cannot be handled
1979  *      by the plugin.
1980  *
1981  * @retval MP_STATUS_INVALID_OBJECT_TYPE
1982  *          Returned if oid does not specify any valid object type.
1983  *
1984  *******************************************************************************
1985  */
1986 MP_STATUS MP_SetLogicalUnitLoadBalanceType(
1987     MP_OID               logicalUnitOid,
1988     MP_LOAD_BALANCE_TYPE loadBalance
1989 );
1990 
1991 /**
1992  *******************************************************************************
1993  *
1994  * Set the weight to be assigned to a particular path.
1995  *
1996  * @param  pathOid
1997  *      The object ID of the path logical unit.
1998  *
1999  * @param  weight
2000  *      weight that will be assigned to the path logical unit.
2001  *
2002  * @return An MP_STATUS indicating if the operation was successful or if
2003  *         an error occurred.
2004  *
2005  * @retval MP_STATUS_SUCCESS
2006  *         Returned when the operation is successful.
2007  *
2008  * @retval MP_STATUS_OBJECT_NOT_FOUND
2009  *      Returned when the MP Path specified by the PathOid could not be
2010  *      found.
2011  *
2012  * @retval MP_STATUS_UNSUPPORTED
2013  *      Returned when the implementation does not support the API
2014  *
2015  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2016  *          Returned if oid does not specify any valid object type.
2017  *
2018  * @retval MP_STATUS_FAILED
2019  *          Returned when the operation failed.
2020  *
2021  * @retval MP_STATUS_INVALID_WEIGHT
2022  *          Returned when the weight parameter is greater than the plugin's
2023  *      maxWeight property.
2024  *
2025  *******************************************************************************
2026  */
2027 MP_STATUS MP_SetPathWeight(
2028     MP_OID    pathOid,
2029     MP_UINT32 weight
2030 );
2031 
2032 /**
2033  *******************************************************************************
2034  *
2035  * Set the default load balance policy for the plugin.
2036  *
2037  * @param  oid
2038  *      The object ID of the plugin
2039  *
2040  * @param  loadBalance
2041  *      The desired default load balance policy for the specified plugin.
2042  *
2043  * @return An MP_STATUS indicating if the operation was successful or if
2044  *         an error occurred.
2045  *
2046  * @retval MP_STATUS_SUCCESS
2047  *         Returned when the operation is successful.
2048  *
2049  * @retval MP_STATUS_OBJECT_NOT_FOUND
2050  *      Returned when the the plugin specified by @ref oid could not be
2051  *      found.
2052  *
2053  * @retval MP_STATUS_INVALID_PARAMETER
2054  *      Returned if the oid of the object is not valid.
2055  *
2056  * @retval MP_STATUS_UNSUPPORTED
2057  *      Returned when the implementation does not support the API
2058  *
2059  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2060  *          Returned if oid does not specify any valid object type.
2061  *
2062  * @retval MP_STATUS_FAILED
2063  *          Returned when the specified loadBalance type cannot be handled
2064  *      by the plugin.
2065  *
2066  *******************************************************************************
2067  */
2068 MP_STATUS MP_SetPluginLoadBalanceType(
2069     MP_OID               oid,
2070     MP_LOAD_BALANCE_TYPE loadBalance
2071 );
2072 
2073 /**
2074  *******************************************************************************
2075  *
2076  * Set the failback polling rates. Setting both rates to zero disables polling.
2077  *
2078  * @param  pluginOid
2079  *      The object ID of either the plugin or a multipath logical unit.
2080  *
2081  * @param  pollingRate
2082  *      The value to be set in MP_PLUGIN_PROPERTIES current pollingRate or
2083  *	MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES pollingRate.
2084  *
2085  * @return An MP_STATUS indicating if the operation was successful or if
2086  *         an error occurred.
2087  *
2088  * @retval MP_STATUS_SUCCESS
2089  *         Returned when the operation is successful.
2090  *
2091  * @retval MP_STATUS_OBJECT_NOT_FOUND
2092  *      Returned when the the plugin specified by @ref oid could not be
2093  *      found.
2094  *
2095  * @retval MP_STATUS_INVALID_PARAMETER
2096  *      Returned if one of the polling values is outside the range
2097  *      supported by the driver.
2098  *
2099  * @retval MP_STATUS_UNSUPPORTED
2100  *      Returned when the implementation does not support the API
2101  *
2102  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2103  *          Returned if oid does not specify any valid object type.
2104  *
2105  *******************************************************************************
2106  */
2107 MP_STATUS MP_SetFailbackPollingRate(
2108     MP_OID    oid,
2109     MP_UINT32 pollingRate
2110 );
2111 
2112 /**
2113  *******************************************************************************
2114  *
2115  * Set the probing polling rates. Setting both rates to zero disables polling.
2116  *
2117  * @param  pluginOid
2118  *      The object ID of either the plugin or a multipath logical unit.
2119  *
2120  * @param  pollingRate
2121  *      The value to be set in MP_PLUGIN_PROPERTIES current pollingRate or
2122  *	MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES pollingRate.
2123  *
2124  * @return An MP_STATUS indicating if the operation was successful or if
2125  *         an error occurred.
2126  *
2127  * @retval MP_STATUS_SUCCESS
2128  *         Returned when the operation is successful.
2129  *
2130  * @retval MP_STATUS_OBJECT_NOT_FOUND
2131  *      Returned when the the plugin specified by @ref oid could not be
2132  *      found.
2133  *
2134  * @retval MP_STATUS_INVALID_PARAMETER
2135  *      Returned if one of the polling values is outside the range
2136  *      supported by the driver.
2137  *
2138  * @retval MP_STATUS_UNSUPPORTED
2139  *      Returned when the implementation does not support the API
2140  *
2141  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2142  *          Returned if oid does not specify any valid object type.
2143  *
2144  *******************************************************************************
2145  */
2146 MP_STATUS MP_SetProbingPollingRate(
2147     MP_OID    oid,
2148     MP_UINT32 pollingRate
2149 );
2150 
2151 /**
2152  *******************************************************************************
2153  *
2154  * Set proprietary properties in supported object instances.
2155  *
2156  * @param  pluginOid
2157  *      The object ID of MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES,
2158  *	MP_PLUGIN_PROPERTIES or MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES.
2159  *
2160  * @param  count
2161  *	   The number of valid items in pPropertyList.
2162  *
2163  * @param  pPropertyList
2164  *	   A pointer to an array of property name/value pairs. This array must
2165  *	   contain the same number of elements as count.
2166  *
2167  * @return An MP_STATUS indicating if the operation was successful or if
2168  *         an error occurred.
2169  *
2170  * @retval MP_STATUS_SUCCESS
2171  *         Returned when the operation is successful.
2172  *
2173  * @retval MP_STATUS_OBJECT_NOT_FOUND
2174  *      Returned when the the plugin specified by @ref oid could not be
2175  *      found.
2176  *
2177  * @retval MP_STATUS_INVALID_PARAMETER
2178  *      Returned if one of the polling values is outside the range
2179  *      supported by the driver.
2180  *
2181  * @retval MP_STATUS_UNSUPPORTED
2182  *      Returned when the implementation does not support the API
2183  *
2184  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2185  *          Returned if oid does not specify any valid object type.
2186  *
2187  *******************************************************************************
2188  */
2189 MP_STATUS MP_SetProprietaryProperties(
2190     MP_OID    oid,
2191     MP_UINT32 count,
2192     MP_PROPRIETARY_PROPERTY *pPropertyList
2193 );
2194 
2195 /**
2196  *******************************************************************************
2197  *
2198  * Set the access state for a list of target port groups. This allows
2199  * a client to force a failover or failback to a desired set of target port
2200  * groups.
2201  *
2202  * @param  luOid
2203  *      The object ID of the logical unit where the command is sent.
2204  *
2205  * @param  count
2206  *      The number of valid items in the pTpgStateList.
2207  *
2208  * @param  pTpgStateList
2209  *      A pointer to an array of TPG/access-state values. This array must
2210  *      contain the same number of elements as @ref count.
2211  *
2212  * @return An MP_STATUS indicating if the operation was successful or if
2213  *         an error occurred.
2214  *
2215  * @retval MP_STATUS_SUCCESS
2216  *         Returned when the operation is successful.
2217  *
2218  * @retval MP_STATUS_OBJECT_NOT_FOUND
2219  *      Returned when the MP_MULTIPATH_LOGICAL_UNIT associated with @ref
2220  *      oid could not be found.
2221  *
2222  * @retval MP_STATUS_INVALID_PARAMETER
2223  *      Returned if pTpgStateList is null or if one of the TPGs referenced
2224  *      in the list is not associated with the specified MP logical unit.
2225  *
2226  * @retval MP_STATUS_UNSUPPORTED
2227  *      Returned when the implementation does not support the API
2228  *
2229  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2230  *          Returned if oid does not specify any valid object type.
2231  *
2232  * @retval MP_STATUS_ACCESS_STATE_INVALID
2233  *         Returned if the target device returns a status indicating the caller
2234  *     is attempting to establish an illegal combination of access states.
2235  *
2236  * @retval MP_STATUS_FAILED
2237  *          Returned if the underlying interface failed the commend for some
2238  *      reason other than MP_STATUS_ACCESS_STATE_INVALID
2239  *
2240  *******************************************************************************
2241  */
2242 MP_STATUS MP_SetTPGAccess(
2243     MP_OID             luOid,
2244     MP_UINT32          count,
2245     MP_TPG_STATE_PAIR *pTpgStateList
2246 );
2247 
2248 /**
2249  ******************************************************************************
2250  *
2251  * The APIs that are associated with event support.
2252  *
2253  * - MP_RegisterForObjectPropertyChanges
2254  * - MP_DeregisterForObjectPropertyChanges
2255  * - MP_RegisterForObjectVisibilityChanges
2256  * - MP_DeregisterForObjectVisibilityChanges
2257  *
2258  ******************************************************************************
2259  */
2260 
2261 /**
2262  *******************************************************************************
2263  *
2264  * Registers a client function that is to be called
2265  * whenever the property of an an object changes.
2266  *
2267  * @param  pClientFn,
2268  *      A pointer to an MP_OBJECT_PROPERTY_FN function defined by the
2269  *      client. On successful return this function will be called to
2270  *      inform the client of objects that have had one or more properties
2271  *      change.
2272  *
2273  * @param  objectType
2274  *      The type of object the client wishes to deregister for
2275  *      property change callbacks. If null, then all objects types are
2276  *      deregistered.
2277  *
2278  * @param  pCallerData
2279  *      A pointer that is passed to the callback routine with each event.
2280  *      This may be used by the caller to correlate the event to source of
2281  *      the registration.
2282  *
2283  * @param  pluginOid
2284  *      A plugin oid that the client wishes to deregister for property change.
2285  *
2286  * @return An MP_STATUS indicating if the operation was successful or if
2287  *         an error occurred.
2288  *
2289  * @retval MP_STATUS_SUCCESS
2290  *         Returned when the operation is successful.
2291  *
2292  * @retval MP_STATUS_INVALID_PARAMETER
2293  *      Returned if pClientFn is NULL or specifies a memory area
2294  *      that is not executable.
2295  *
2296  * @retval MP_STATUS_FN_REPLACED
2297  *      Returned when an existing client function is replaced with the one
2298  *      specified in pClientFn.
2299  *
2300  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2301  *          Returned if objectType does not specify any valid object type.
2302  *
2303  *******************************************************************************
2304  */
2305 MP_STATUS MP_RegisterForObjectPropertyChanges(
2306     MP_OBJECT_PROPERTY_FN   pClientFn,
2307     MP_OBJECT_TYPE	    objectType,
2308     void		    *pCallerData,
2309     MP_OID		    pluginOid
2310 );
2311 
2312 /**
2313  *******************************************************************************
2314  *
2315  * Deregisters a previously registered client function that is to be invoked
2316  * whenever an object's property changes.
2317  *
2318  * @param  pClientFn,
2319  *      A pointer to an MP_OBJECT_PROPERTY_FN function defined by the
2320  *      client that was previously registered using
2321  *      the MP_RegisterForObjectPropertyChanges API. On successful return
2322  *      this function will no longer be called to inform the client of
2323  *      object property changes.
2324  *
2325  * @param  objectType
2326  *      The type of object the client wishes to deregister for
2327  *      property change callbacks. If null, then all objects types are
2328  *      deregistered.
2329  *
2330  * @param  pluginOid
2331  *      A plugin oid that the client wishes to deregister for property change.
2332  *
2333  * @return An MP_STATUS indicating if the operation was successful or if
2334  *         an error occurred.
2335  *
2336  * @retval MP_STATUS_SUCCESS
2337  *         Returned when the operation is successful.
2338  *
2339  * @retval MP_STATUS_INVALID_PARAMETER
2340  *      Returned if pClientFn is NULL or specifies a memory area
2341  *      that is not executable.
2342  *
2343  * @retval MP_STATUS_UNKNOWN_FN
2344  *      Returned if pClientFn is not the same as the previously registered
2345  *      function.
2346  *
2347  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2348  *          Returned if objectType does not specify any valid object type.
2349  *
2350  * @retval MP_STATUS_FAILED
2351  *          Returned if pClientFn deregistration is not possible at this time.
2352  *
2353  *******************************************************************************
2354  */
2355 MP_STATUS MP_DeregisterForObjectPropertyChanges(
2356     MP_OBJECT_PROPERTY_FN   pClientFn,
2357     MP_OBJECT_TYPE	    objectType,
2358     MP_OID		    pluginOid
2359 );
2360 
2361 /**
2362  *******************************************************************************
2363  *
2364  * Registers a client function that is to be called
2365  * whenever a high level object appears or disappears.
2366  *
2367  * @param  pClientFn,
2368  *      A pointer to an MP_OBJECT_VISIBILITY_FN function defined by the
2369  *      client. On successful return this function will be called to
2370  *      inform the client of objects whose visibility has changed.
2371  *
2372  * @param  objectType
2373  *      The type of object the client wishes to deregister for
2374  *      property change callbacks. If null, then all objects types are
2375  *      deregistered.
2376  *
2377  * @param  pCallerData
2378  *      A pointer that is passed to the callback routine with each event.
2379  *      This may be used by the caller to correlate the event to source of
2380  *      the registration.
2381  *
2382  * @param  pluginOid
2383  *      A plugin oid that the client wishes to deregister for property change.
2384  *
2385  * @return An MP_STATUS indicating if the operation was successful or if
2386  *         an error occurred.
2387  *
2388  * @retval MP_STATUS_SUCCESS
2389  *         Returned when the operation is successful.
2390  *
2391  * @retval MP_STATUS_INVALID_PARAMETER
2392  *      Returned if pClientFn is NULL or specifies a memory area
2393  *      that is not executable.
2394  *
2395  * @retval MP_STATUS_FN_REPLACED
2396  *      Returned when an existing client function is replaced with the one
2397  *      specified in pClientFn.
2398  *
2399  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2400  *          Returned if objectType does not specify any valid object type.
2401  *
2402  *******************************************************************************
2403  */
2404 MP_STATUS MP_RegisterForObjectVisibilityChanges(
2405     MP_OBJECT_VISIBILITY_FN pClientFn,
2406     MP_OBJECT_TYPE	    objectType,
2407     void		    *pCallerData,
2408     MP_OID		    pluginOid
2409 );
2410 
2411 /**
2412  *******************************************************************************
2413  *
2414  * Deregisters a previously registered client function that is to be invoked
2415  * whenever a high level object appears or disappears.
2416  *
2417  * @param  pClientFn,
2418  *      A pointer to an MP_OBJECT_VISIBILITY_FN function defined by the
2419  *      client that was previously registered using
2420  *      the MP_RegisterForObjectVisibilityChanges API. On successful return
2421  *      this function will no longer be called to inform the client of
2422  *      object property changes.
2423  *
2424  * @param  objectType
2425  *      The type of object the client wishes to deregister for visibility
2426  *      change callbacks. If null, then all objects types are
2427  *      deregistered.
2428  *
2429  * @param  pluginOid
2430  *      A plugin oid that the client wishes to deregister for property change.
2431  *
2432  * @return An MP_STATUS indicating if the operation was successful or if
2433  *         an error occurred.
2434  *
2435  * @retval MP_STATUS_SUCCESS
2436  *         Returned when the operation is successful.
2437  *
2438  * @retval MP_STATUS_INVALID_PARAMETER
2439  *      Returned if pClientFn is NULL or specifies a memory area
2440  *      that is not executable.
2441  *
2442  * @retval MP_STATUS_UNKNOWN_FN
2443  *      Returned if pClientFn is not the same as the previously registered
2444  *      function.
2445  *
2446  * @retval MP_STATUS_INVALID_OBJECT_TYPE
2447  *          Returned if objectType does not specify any valid object type.
2448  *
2449  * @retval MP_STATUS_FAILED
2450  *          Returned if pClientFn deregistration is not possible at this time.
2451  *
2452  *******************************************************************************
2453  */
2454 MP_STATUS MP_DeregisterForObjectVisibilityChanges(
2455     MP_OBJECT_VISIBILITY_FN pClientFn,
2456     MP_OBJECT_TYPE          objectType,
2457     MP_OID		    pluginOid
2458 );
2459 
2460 /**
2461  ******************************************************************************
2462  *
2463  * The utility APIs
2464  *
2465  * - MP_CompareOIDs
2466  * - MP_FreeOidList
2467  * - MP_RegisterPlugin
2468  * - MP_DeregisterPlugin
2469  *
2470  ******************************************************************************
2471  */
2472 
2473 /**
2474  *******************************************************************************
2475  *
2476  * Compare two Oids for equality to see whether they refer to the same object.
2477  *
2478  * @param  oid1
2479  *          Oid to compare.
2480  *
2481  * @param  oid2
2482  *          Oid to compare.
2483  *
2484  * @return An MP_STATUS indicating if the operation was successful or if
2485  *         an error occurred.
2486  *
2487  * @retval MP_STATUS_SUCCESS
2488  *         Returned when the two Oids do refer to the same object.
2489  *
2490  * @retval MP_STATUS_FAILED
2491  *      Returned if the Oids don't compare.
2492  *
2493  *******************************************************************************
2494  */
2495 MP_STATUS MP_CompareOIDs(
2496     MP_OID oid1,
2497     MP_OID oid2
2498 );
2499 
2500 /**
2501  *******************************************************************************
2502  *
2503  * Frees memory returned by an MP API.
2504  *
2505  * @param  pMemory
2506  *      A pointer to the memory returned by an MP API. On successful
2507         return, the allocated memory is freed.
2508  *
2509  * @return An MP_STATUS indicating if the operation was successful or if
2510  *         an error occurred.
2511  *
2512  * @retval MP_STATUS_SUCCESS
2513  *         Returned when pPluginId is deregistered successfully.
2514  *
2515  * @retval MP_STATUS_INVALID_PARAMETER
2516  *      Returned if pMemory is NULL or specifies a memory area to which
2517  *      data cannot be written.
2518  *
2519  *******************************************************************************
2520  */
2521 MP_STATUS MP_FreeOidList(
2522     MP_OID_LIST *pOidList
2523 );
2524 
2525 /**
2526  *******************************************************************************
2527  *
2528  * Registers a plugin with common library.  The implementation of this routine
2529  * is based on configuration file /etc/mpapi.conf that contains a list of
2530  * plugin libraries.
2531  *
2532  * @param  pPluginId
2533  *      A pointer to the key name shall be the reversed domain name of
2534  *      the vendor followed by followed by the vendor specific name for
2535  *      the plugin that uniquely identifies the plugin.
2536  *
2537  * @param  pFileName
2538  *      The full path to the plugin library.
2539  *
2540  * @return An MP_STATUS indicating if the operation was successful or if
2541  *         an error occurred.
2542  *
2543  * @retval MP_STATUS_SUCCESS
2544  *         Returned when pPluginId is deregistered successfully.
2545  *
2546  * @retval MP_STATUS_INVALID_PARAMETER
2547  *      Returned if pPluginId is NULL or specifies a memory area that
2548  *      is not executable.
2549  *
2550  * @retval MP_STATUS_FAILED
2551  *          Returned if pClientFn deregistration is not possible at this time.
2552  *
2553  *******************************************************************************
2554  */
2555 MP_STATUS MP_RegisterPlugin(
2556     MP_WCHAR *pPluginId,
2557     MP_CHAR *pFileName
2558 );
2559 
2560 /**
2561  *******************************************************************************
2562  *
2563  * Deregisters a plugin from the common library.
2564  *
2565  * @param  pPluginId
2566  *      A pointer to a Plugin ID previously registered using
2567  *      the MP_RegisterPlugin API..
2568  *
2569  * @return An MP_STATUS indicating if the operation was successful or if
2570  *         an error occurred.
2571  *
2572  * @retval MP_STATUS_SUCCESS
2573  *         Returned when pPluginId is deregistered successfully.
2574  *
2575  * @retval MP_STATUS_INVALID_PARAMETER
2576  *      Returned if pPluginId is NULL or specifies a memory area that
2577  *      is not executable.
2578  *
2579  * @retval MP_STATUS_FAILED
2580  *          Returned if pClientFn deregistration is not possible at this time.
2581  *
2582  *******************************************************************************
2583  */
2584 MP_STATUS MP_DeregisterPlugin(
2585     MP_WCHAR *pPluginId
2586 );
2587 
2588 #endif
2589 
2590 #ifdef __cplusplus
2591 };
2592 #endif
2593 
2594