/* Disclaimer: The users of these APIs are considered advanced users who are familiar with the command-line parameters passed to each qcommand. Error checking and validation of command-line parameters will be very limited and will not exceed what the command-line framework already provides */ #ifndef __QAPI_H__ #define __QAPI_H__ /*! \file QAPI.h \brief QAPI header file This is the header file for QAPIs and contains all necessary declarations required to invoke QAPIs. */ /*----------------------------------- Include headers -----------------------------------*/ #include /*----------------------------------- Macros -----------------------------------*/ /*! \def QAPI_VERSION \brief QAPI version */ #define QAPI_VERSION "1.0" /*----------------------------------- Enums -----------------------------------*/ /*! \enum QAPI_OutputMode \brief QAPI output mode */ enum QAPI_OutputMode { QAPI_OUTPUTMODE_CONSOLE, //!< Command output is redirected to console QAPI_OUTPUTMODE_CALLBACK //!< Command output is redirected to callback routine }; /*! \enum QAPI_QScriptOutputFormat \brief QScript command output format */ enum QAPI_QScriptOutputFormat { QAPI_QSCRIPTOUTPUTFORMAT_XML, //!< QSript output in XML format QAPI_QSCRIPTOUTPUTFORMAT_CSV, //@< QScript output in CSV format QAPI_QSCRIPTOUTPUTFORMAT_FORMAT //@< QScript output formatted in q-command style }; /*! \enum QAPI_ListSubType \brief Qlist subcommand types */ enum QAPI_ListSubType { QAPI_LIST_CLIENT //!< Subcommand 'client' }; /*! \enum QAPI_OperationSubType \brief Operation subcommand types */ enum QAPI_OperationSubType { QAPI_OPERATION_BACKUP //!< Subcommand 'backup' }; #ifdef __cplusplus extern "C" { #endif /*----------------------------------- Structures -----------------------------------*/ /*! \struct QAPI_Status \brief QAPI return status */ typedef struct { unsigned int code; //!< Return status code char description[1024]; //!< Return status description } QAPI_Status; /*! \struct QAPI_InitParameters \brief QAPI configuration parameters needed by QAPI_Init */ typedef struct { const char * version; //!< QAPI version. Make sure this //!< is always set to QAPI_VERSION. } QAPI_InitParameters; /*! \struct QAPI_Output \brief QAPI output parameters */ typedef struct { QAPI_OutputMode outputMode; //!< Output mode. QAPI output will //!< be processed based on this value. int (*outDataReader)(char *, int, void *); //!< Callback function which will //!< be used to redirect output when //!< outputMode is set to CALLBACK. //!< This callback takes three //!< arguments, first argument is //!< a pointer to character stream //!< of size specified in second //!< parameter. Third parameter is //!< a void pointer which is not //!< interpreted by QAPIs and user //!< can use it to store context //!< information. } QAPI_Output; /*----------------------------------- Functions -----------------------------------*/ /*! \fn QAPI_Status QAPI_Init(QAPI_InitParameters initParams) \brief API to set configuration parameters for QAPI. This API takes configuration parameters like output mode etc. needed by QAPIs. User must call this API before invoking any other API. \param [in] initParams Configuration parameters \return Command return code */ QAPI_Status QAPI_Init(QAPI_InitParameters initParams); /*! \fn QAPI_Status QAPI_Login(const char * commandString) \brief API to login to a Commserver. This API is functionally equivalent to 'qlogin' command. It accepts the commandline parameters passed to 'qlogin' command and starts a new login session to the specified Commserver. This API must be called before running any other QAPIs. Output of the API is either returned through callback function set through QAPI_Init or displayed on the console, depending on output mode set through QAPI_Init. \param [in] commandString Commandline parameters of 'qlogin' command \param [in,out] output Output parameters \return Command return code */ QAPI_Status QAPI_Login(const char * commandString, QAPI_Output * ouput); /*! \fn QAPI_Status QAPI_Operation(QAPI_OperationSubType subcommandType, const char * commandString) \brief API to start an operation. This API is functionally equivalent to 'qoperation' command. It accepts the commandline parameters passed to 'qoperation' command, barring subcommand type, say 'backup', 'restore', etc. Subcommand type is passed through first parameter 'subcommandType'. Output of the API is either returned through callback function set through QAPI_Init or displayed on the console, depending on output mode set through QAPI_Init. \param [in] subcommandType Operation subcommand type \param [in] commandString Commandline parameters of 'qoperation' command, barring subcommand name \param [in,out] output Output parameters \return Command return code */ QAPI_Status QAPI_Operation(QAPI_OperationSubType subcommandType, const char * commandString, QAPI_Output * ouput); /*! \fn QAPI_Status QAPI_Logout(const char * commandString) \brief API to logout from a Commserver. This API is functionally equivalent to 'qlogout' command. It accepts the commandline parameters passed to 'qlogout' command and terminates the login session created by 'qlogin' command. Once this API is called, user will have to call QAPI_Login() API in order to run more commands. Output of the API is either returned through callback function set through QAPI_Init or displayed on the console, depending on output mode set through QAPI_Init. \param [in] commandString Commandline parameters of 'qlogout' command \param [in,out] output Output parameters \return Command return code */ QAPI_Status QAPI_Logout(const char * commandString, QAPI_Output * ouput); /*! \fn QAPI_Status QAPI_Exit() \brief API to terminate QAPI. This API must be the last API to call and user must invoke QAPI_Init again in order to invoke more QAPIs. \return Command return code */ QAPI_Status QAPI_Exit(); /*----------------------------------- Function type declarations -----------------------------------*/ /*! \typedef QAPI_Init_Type \brief Function type declaration for QAPI_Init */ typedef QAPI_Status (*QAPI_Init_Type)(QAPI_InitParameters); /*! \typedef QAPI_Login_Type \brief Function type declaration for QAPI_Login */ typedef QAPI_Status (*QAPI_Login_Type)(const char *, QAPI_Output *); /*! \typedef QAPI_Operation_Type \brief Function type declaration for QAPI_Operation */ typedef QAPI_Status (*QAPI_Operation_Type)(QAPI_OperationSubType, const char *, QAPI_Output *); /*! \typedef QAPI_Logout_Type \brief Function type declaration for QAPI_Logout */ typedef QAPI_Status (*QAPI_Logout_Type)(const char *, QAPI_Output *); /*! \typedef QAPI_Exit_Type \brief Function type declaration for QAPI_Exit */ typedef QAPI_Status (*QAPI_Exit_Type)(); #ifdef __cplusplus } #endif #endif // __QAPI_H__