OpenClovis Logo

clAmsSAClientApi.h
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : amf
21  * File : clAmsSAClientApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  * This header file contains AMS client API related definitions.
27  ***************************** Editor Commands ********************************
28  * For vi/vim
29  * :set shiftwidth=4
30  * :set softtabstop=4
31  * :set expandtab
32  *****************************************************************************/
33 
34 #ifndef _CL_AMS_SA_CLIENT_API_H_
35 #define _CL_AMS_SA_CLIENT_API_H_
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 /******************************************************************************
42  * Include files needed to compile this file
43  *****************************************************************************/
44 
45 #include <clCommon.h>
46 #include <clCommonErrors.h>
47 
48 #include <clAmsTypes.h>
49 
50 /******************************************************************************
51  * Client API functions.
52  * -- The following are functions invoked by AMS.
53  *****************************************************************************/
54 
55 /*
56  * ClAmsSACSISetCallbackT
57  * ----------------------
58  * AMS calls this function to assign a CSI to a component.
59  *
60  * @param
61  * invocation - back reference to AMS
62  * compName - Name of component
63  * haState - HA state being assigned
64  * csiDescriptor - CSIs to which this fn is targetted
65  *
66  * @returns
67  * Nothing
68  */
69 
70 typedef void (*ClAmsSACSISetCallbackT)(
71  CL_IN ClInvocationT invocation,
72  CL_IN const ClNameT *compName,
73  CL_IN ClAmsHAStateT haState,
74  CL_IN ClAmsCSIDescriptorT csiDescriptor);
75 
76 /*
77  * ClAmsSACSIRemoveCallbackT
78  * -------------------------
79  * AMS calls this function to remove a CSI assignment.
80  *
81  * @param
82  * invocation - back reference to AMS
83  * compName - Name of component
84  * csiName - Name of CSI
85  * csiFlags - operation
86  *
87  * @returns
88  * Nothing
89  */
90 
91 typedef void (*ClAmsSACSIRemoveCallbackT)(
92  CL_IN ClInvocationT invocation,
93  CL_IN const ClNameT *compName,
94  CL_IN const ClNameT *csiName,
95  CL_IN ClAmsCSIFlagsT csiFlags);
96 
97 /*
98  * ClAmsSAPGTrackCallbackT
99  * -----------------------
100  * AMS calls this function to let a component know changes
101  * affecting a protection group. The component must have
102  * previously requested tracking.
103  *
104  * @param
105  * csiName - Name of CSI
106  * notificationBuffer - Where to put results
107  * numMembers - Mumber of members in a PG
108  * error - status of change
109  *
110  * @returns
111  * Nothing
112  */
113 
114 typedef void (*ClAmsSAPGTrackCallbackT)(
115  CL_IN const ClNameT *csiName,
116  CL_IN ClAmsPGNotificationBufferT notificationBuffer,
117  CL_IN ClUint32T numMembers,
118  CL_IN ClRcT error);
119 
120 /*
121  * ClAmsSACompHealthcheckCallbackT
122  * -------------------------------
123  * AMS calls this function to do a healthcheck on a component.
124  *
125  * @param
126  *
127  * @returns
128  * Nothing
129  */
130 
131 typedef void (*ClAmsSACompHealthcheckCallbackT)(
132  CL_IN ClInvocationT invocation,
133  CL_IN const ClNameT *compName,
134  CL_IN ClAmsCompHealthcheckKeyT *healthcheckkey);
135 
136 /*
137  * ClAmsSACompTerminateCallbackT
138  * -----------------------------
139  * AMS calls this function to terminate a component
140  *
141  * @param
142  *
143  * @returns
144  * Nothing
145  */
146 
147 typedef void (*ClAmsSACompTerminateCallbackT)(
148  CL_IN ClInvocationT invocation,
149  CL_IN const ClNameT *compName);
150 
151 /*
152  * ClAmsSAProxiedCompInstantiateCallbackT
153  * --------------------------------------
154  * AMS calls this function to instantiate a proxied component.
155  * This fn is called for the proxy component.
156  *
157  * @param
158  *
159  * @returns
160  * Nothing
161  */
162 
163 typedef void (*ClAmsSAProxiedCompInstantiateCallbackT)(
164  CL_IN ClInvocationT invocation,
165  CL_IN const ClNameT *proxiedCompName);
166 
167 /*
168  * ClAmsSAProxiedCompCleanupCallbackT
169  * ----------------------------------
170  * AMS calls this function to abruptly terminate a proxied component.
171  * This fn is called for the proxy component.
172  *
173  * @param
174  *
175  * @returns
176  * Nothing
177  */
178 
179 typedef void (*ClAmsSAProxiedCompCleanupCallbackT)(
180  CL_IN ClInvocationT invocation,
181  CL_IN const ClNameT *proxiedCompName);
182 
183 typedef struct
184 {
185  ClAmsSACompHealthcheckCallbackT healthcheckCallback;
186  ClAmsSACompTerminateCallbackT compTerminateCallback;
187  ClAmsSACSISetCallbackT csiSetCallback;
188  ClAmsSACSIRemoveCallbackT csiRemoveCallback;
189  ClAmsSAPGTrackCallbackT pgTrackCallback;
190  ClAmsSAProxiedCompInstantiateCallbackT proxiedCompInstantiateCallback;
191  ClAmsSAProxiedCompCleanupCallbackT proxiedCompCleanupCallback;
192 } ClAmsSAClientCallbacksT;
193 
194 /******************************************************************************
195  * SA API functions invoked by client
196  *****************************************************************************/
197 
198 /*
199  * ----- SA Library LifeCycle Management Functions Invoked by Client -----
200  */
201 
202 /*
203  * clAmsSAInitialize
204  * -----------------
205  * Initialize/Start the use of the AMS SA API library.
206  *
207  * @param
208  * amsHandle - Handle returned by AMS to API user
209  * amsCallbacks - Callbacks into API user
210  * version - Versions supported by AMS and user
211  *
212  * @returns
213  * CL_OK - Operation successful
214  * CL_ERR_VERSION_MISMATCH - Error: Version not supported by AMS
215  *
216  */
217 
218 extern ClRcT clAmsSAInitialize(
219  CL_OUT ClAmsClientHandleT *amsHandle,
220  CL_IN const ClAmsSAClientCallbacksT *amsClientCallbacks,
221  CL_INOUT ClVersionT *version);
222 
223 /*
224  * clAmsSAFinalize
225  * ---------------
226  * Finalize/terminate the use of the AMS client API library.
227  *
228  * @param
229  * amsHandle - Handle assigned to API user
230  *
231  * @returns
232  * CL_OK - Operation successful
233  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
234  *
235  */
236 
237 extern ClRcT clAmsSAFinalize(
238  CL_IN ClAmsClientHandleT amsHandle);
239 
240 /*
241  * clAmsSASelectionObjectGet
242  * -------------------------
243  * Get the OS handle associated with amsHandle. This fn may not be
244  * supported by ASP.
245  *
246  * @param
247  * amsHandle - Handle assigned to API user
248  *
249  * @returns
250  * CL_OK - Operation successful
251  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
252  *
253  */
254 
255 extern ClRcT clAmsSASelectionObjectGet(
256  CL_IN ClAmsClientHandleT amsHandle,
257  CL_OUT ClSelectionObjectT *selectionObject);
258 
259 /*
260  * clAmsSADispatch
261  * ---------------
262  * A client can use this fn to invoke pending callbacks. This fn
263  * may not be supported by ASP.
264  *
265  * @param
266  * amsHandle - Handle assigned to API user
267  *
268  * @returns
269  * CL_OK - Operation successful
270  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
271  *
272  */
273 
274 //extern ClRcT clAmsSADispatch(
275  // CL_IN ClAmsClientHandleT amsHandle,
276  // CL_IN ClDispatchFlagsT dispatchFlags);
277 
278 /*
279  * ----- SA Functions Invoked by Client -----
280  */
281 
282 /*
283  * clAmsSAComponentRegister
284  * ------------------------
285  * Register a component.
286  *
287  * @param
288  * amsHandle - Handle assigned to API user
289  * compName - Name of component being registered
290  * proxyCompName - Name of proxy registering the component
291  *
292  * @returns
293  * CL_OK - Operation successful
294  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
295  *
296  */
297 
298 extern ClRcT clAmsSACompRegister(
299  CL_IN ClAmsClientHandleT amsHandle,
300  CL_IN const ClNameT *compName,
301  CL_IN const ClNameT *proxyCompName);
302 
303 /*
304  * clAmsSAComponentUnregister
305  * --------------------------
306  * Unregister a component.
307  *
308  * @param
309  * amsHandle - Handle assigned to API user
310  * compName - Name of component being unregistered
311  * proxyCompName - Name of proxy unregistering the component
312  *
313  * @returns
314  * CL_OK - Operation successful
315  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
316  *
317  */
318 
319 extern ClRcT clAmsSACompUnregister(
320  CL_IN ClAmsClientHandleT amsHandle,
321  CL_IN const ClNameT *compName,
322  CL_IN const ClNameT *proxyCompName);
323 
324 /*
325  * clAmsSAComponentNameGet
326  * -----------------------
327  * Get the name of a component
328  *
329  * @param
330  * amsHandle - Handle assigned to API user
331  * compName - Name of component invoking this fn
332  *
333  * @returns
334  * CL_OK - Operation successful
335  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
336  *
337  */
338 
339 extern ClRcT clAmsSACompNameGet(
340  CL_IN ClAmsClientHandleT amsHandle,
341  CL_OUT ClNameT *compName);
342 
343 /*
344  * clAmsSACSIHAStateGet
345  * --------------------
346  * Get HA state associated with a CSI
347  *
348  * @param
349  * amsHandle - Handle assigned to API user
350  * compName - Name of component
351  * csiName - Name of CSI
352  * haState - ha state
353  *
354  * @returns
355  * CL_OK - Operation successful
356  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
357  *
358  */
359 
360 extern ClRcT clAmsSACSIHAStateGet(
361  CL_IN ClAmsClientHandleT amsHandle,
362  CL_IN const ClNameT *compName,
363  CL_IN const ClNameT *csiName,
364  CL_OUT ClAmsHAStateT *haState);
365 
366 /*
367  * clAmsSACSIQuiescingComplete
368  * ---------------------------
369  * Inform AMS that client has stopped processing a workload.
370  *
371  * @param
372  * amsHandle - Handle assigned to API user
373  * invocation - back reference to AMS for
374  * prior operation
375  * error - status of operation
376  *
377  * @returns
378  * CL_OK - Operation successful
379  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
380  *
381  */
382 
383 extern ClRcT clAmsSACSIQuiescingComplete(
384  CL_IN ClAmsClientHandleT amsHandle,
385  CL_IN ClInvocationT invocation,
386  CL_IN ClRcT error);
387 
388 /*
389  * clAmsSAPGTrack
390  * --------------
391  * Request tracking from AMS for status of a PG.
392  *
393  * @param
394  * amsHandle - Handle assigned to API user
395  * csiName - Name of CSI / PG
396  * trackFlags - Type of tracking desired
397  * notificationBuffer - Where to put results
398  *
399  * @returns
400  * CL_OK - Operation successful
401  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
402  *
403  */
404 
405 extern ClRcT clAmsSAPGTrack(
406  CL_IN ClAmsClientHandleT amsHandle,
407  CL_IN ClNameT *csiName,
408  CL_IN ClUint8T trackFlags,
409  CL_IN ClAmsPGNotificationBufferT *notificationBuffer);
410 
411 /*
412  * clAmsSAPGTrackStop
413  * ------------------
414  * Indicate tracking is no longer required for PG.
415  *
416  * @param
417  * amsHandle - Handle assigned to API user
418  * csiName - Name of CSI / PG
419  *
420  * @returns
421  * CL_OK - Operation successful
422  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
423  *
424  */
425 
426 extern ClRcT clAmsSAPGTrackStop(
427  CL_IN ClAmsClientHandleT amsHandle,
428  CL_IN const ClNameT *csiName);
429 
430 /*
431  * clAmsSAResponse
432  * ---------------
433  * Send a delayed reponse from client to AMS about a prior
434  * operation.
435  *
436  * @param
437  * amsHandle - Handle assigned to API user
438  * invocation - back reference to AMS for
439  * prior operation
440  * error - status of operation
441  *
442  * @returns
443  * CL_OK - Operation successful
444  * CL_ERR_INVALID_HANDLE - Error: Handle was invalid
445  *
446  */
447 
448 extern ClRcT clAmsSAResponse(
449  CL_IN ClAmsClientHandleT amsHandle,
450  CL_IN ClInvocationT invocation,
451  CL_IN ClRcT error);
452 
453 /*
454  * TODO
455  *
456  * Functions currently not present in this file
457  *
458  * clAmsSAPmStart
459  * clAmsSAPmStop
460  * clAmsSAHealthcheckStart
461  * clAmsSAHealthcheckStop
462  * clAmsSAHealthcheckConfirm
463  */
464 
465 #ifdef __cplusplus
466 }
467 #endif
468 
469 #endif /* _CL_AMS_SA_CLIENT_API_H_ */
Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen