mksCommand.h File Reference

---

Detailed Description

The header file defining the main functions used for accessing the MKS Integrity Server and MKS Integrity Client via the Integrity API.

This header file contains various enums and functions used for logging messages to the standard MKS Integrity API log file.

Definition in file mksCommand.h.

#include "mksResponse.h"
#include "mksError.h"

Go to the source code of this file.

Data Structures
struct	_mksCommand
Defines
#define	AA   "aa"
#define	IM   "im"
#define	TM   "tm"
#define	RQ   "rq"
#define	INTEGRITY   "integrity"
#define	SI   "si"
#define	SD   "sd"
Typedefs
typedef enum mksExecuteTypeEnum	mksExecuteType
typedef _mksCmdRunner *	mksCmdRunner
typedef _mksIntegrationPoint *	mksIntegrationPoint
typedef _mksMultiValue *	mksMultiValue
typedef _mksOptionList *	mksOptionList
typedef _mksSelectionList *	mksSelectionList
typedef _mksSession *	mksSession
typedef _mksCommand *	mksCommand
Enumerations
enum	mksExecuteTypeEnum { NO_INTERIM = 0, INTERIM_NO_CACHE = 1, INTERIM_CACHE = 2 }
Functions
mksResponse	mksCmdRunnerExecCmd (mksCmdRunner cr, const mksCommand cmd, const mksExecuteType type)
	Function used to execute a command contained within an mksCommand struct.
mksResponse	mksCmdRunnerExecArr (mksCmdRunner cr, const wchar_t **arr, const int len, const mksExecuteType type)
	Function used to execute a command specified by the 'arr' array.
mksResponse	mksCmdRunnerExecArrWithVendor (mksCmdRunner cr, const wchar_t **arr, const int len, const mksExecuteType type, const char *vendor)
	Function used to execute a third party command specified by the 'arr' array.
mksrtn	mksCmdRunnerInterrupt (mksCmdRunner cr)
	Function used to interrupt an mksCmdRunner while it is executing a long running command or is in the middle of processing an interim response.
mksrtn	mksCmdRunnerIsFinished (const mksCmdRunner cr, unsigned short *flag)
	Function used to check to see if the mksCmdRunner has completed executing a command or not.
mksrtn	mksCmdRunnerGetDefaultHostname (const mksCmdRunner cr, char *buf, size_t len)
	Function used to retrieve the default hostname from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultPort (const mksCmdRunner cr, unsigned int *port)
	Function used to retrieve the default port from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultUsername (const mksCmdRunner cr, char *buf, size_t len)
	Function used to retrieve the default username from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultUsernameWide (const mksCmdRunner cr, wchar_t *buf, size_t len)
	Function used to retrieve the default username from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultPassword (const mksCmdRunner cr, char *buf, size_t len)
	Function used to retrieve the default password from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultPasswordWide (const mksCmdRunner cr, wchar_t *buf, size_t len)
	Function used to retrieve the default password from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultImpersonationUser (const mksCmdRunner cr, char *buf, size_t len)
	Function used to retrieve the default impersonation user from the mksCmdRunner.
mksrtn	mksCmdRunnerGetDefaultImpersonationUserWide (const mksCmdRunner cr, wchar_t *buf, size_t len)
	Function used to retrieve the default impersonation user from the mksCmdRunner.
mksSession	mksCmdRunnerGetSession (const mksCmdRunner cr)
	Function used to retrieve the mksSession associated with the given mksCmdRunner.
mksrtn	mksCmdRunnerSetCallerID (mksCmdRunner cr, const char *str)
	Funtion used to set an identifier for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultHostname (mksCmdRunner cr, const char *str)
	Function used to set the default hostname for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultPort (mksCmdRunner cr, const unsigned int port)
	Function used to set the default port for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultUsername (mksCmdRunner cr, const char *str)
	Function used to set the default username for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultUsernameWide (mksCmdRunner cr, const wchar_t *str)
	Function used to set the default username for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultPassword (mksCmdRunner cr, const char *str)
	Function used to set the default password for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultPasswordWide (mksCmdRunner cr, const wchar_t *str)
	Function used to set the default password for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultImpersonationUser (mksCmdRunner cr, const char *str)
	Function used to set the default impersonation user for the mksCmdRunner.
mksrtn	mksCmdRunnerSetDefaultImpersonationUserWide (mksCmdRunner cr, const wchar_t *str)
	Function used to set the default impersonation user for the mksCmdRunner.
void	mksReleaseCmdRunner (mksCmdRunner cr)
	Function used to release the mksCmdRunner.
mksCommand	mksCreateCommand (void)
	Function used to create and initialize an mksCommand struct.
void	mksReleaseCommand (mksCommand cmd)
mksrtn	mksAPIInitialize (const char *logfile)
	Function used to initialize the API.
mksrtn	mksCreateLocalIntegrationPoint (mksIntegrationPoint *ip, const unsigned short autostart)
	Function used to create an mksIntegrationPoint to the local Integrity Client. As of MKS 2009, this function is deprecated in favour of the function through which you would be asked to indicate the API version.
mksrtn	mksCreateLocalAPIConnector (mksIntegrationPoint *ip, const unsigned short apiMajorVersion, const unsigned short apiMinorVersion, const unsigned short autostart)
	Function used to create an mksIntegrationPoint to the local Integrity Client. Through this function, an API version can be requested in the form of a major and minor numbers. This version would correspond to the version of the Integrition platform (for example MKS 2009 is version 4.10; major number 4, minor number 10) for which the integration was written and verified. By indicating the request version, should the Integrity platform be upgraded, the platform will at least be advised that the integration is still expecting API handling as per the requested version.
mksrtn	mksCreateIntegrationPoint (mksIntegrationPoint *ip, const char *host, const unsigned int port, const unsigned short secure)
	Function used to create a generic mksIntegrationPoint to either an Integrity Client or an Integrity Server (both of which can be either local or remote). As of MKS 2009, this function is deprecated in favour of the function through which you would be asked to indicate the API version.
mksrtn	mksCreateAPIConnector (mksIntegrationPoint *ip, const char *host, const unsigned int port, const unsigned short secure, const unsigned short apiMajorVersion, const unsigned short apiMinorVersion)
	Function used to create a generic mksIntegrationPoint to either an Integrity Client or an Integrity Server (both of which can be either local or remote). Through this function, an API version can be requested in the form of a major and minor numbers. This version would correspond to the version of the Integrition platform (for example MKS 2009 is version 4.10; major number 4, minor number 10) for which the integration was written and verified. By indicating the request version, should the Integrity platform be upgraded, the platform will at least be advised that the integration is still expecting API handling as per the requested version.
wchar_t *	mksAPIStrError (const mksrtn error)
	Function used to retrieve a string represenation of a particular mksrtn error code.
mksrtn	mksGetError (void)
	For those functions that return objects, you can call mksGetError() to get the specific reason why the object wasn't returned.
mksrtn	mksAPITerminate (void)
	Function called after use of the Integrity API has been completed.
mksrtn	mksGetCommonSession (mksSession *session, const mksIntegrationPoint ip)
	Function used to retrieve the common mksSession instance from the mksIntegrationPoint. By default, the common mksSession will use the API request version as indicated when the mksIntegrationPoint was created.
mksrtn	mksCreateSession (mksSession *session, const mksIntegrationPoint ip, const char *user, const char *pass)
	Function used to retrieve a non-common mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created.
mksrtn	mksCreateNamedSession (mksSession *session, const mksIntegrationPoint ip, const char *integrationAppID, const char *user, const char *pass)
	Function used to create a named mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created. The name is to be defined by the integration application and will be used in Integrity as an identifier for the integration application.
mksrtn	mksCreateNamedVersionedSession (mksSession *session, const mksIntegrationPoint ip, const char *integrationAppID, const unsigned short apiMajorVersion, const unsigned short apiMinorVersion, const char *user, const char *pass)
	Function used to create a named versioned mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created. The name is to be defined by the integration application and will be used in Integrity as an identifier for the integration application.
mksrtn	mksCreateVersionedSession (mksSession *session, const mksIntegrationPoint ip, const unsigned short apiMajorVersion, const unsigned short apiMinorVersion, const char *user, const char *pass)
	Function used to retrieve a non-common mksSession instance from the mksIntegrationPoint. This function allow for the mksSession to be created with its own explicit API request version, independent of the one specified when the mksIntegrationPoint was created. (Refer to the docs on the creation of the mksIntegrationPoint for comments on the versioning).
mksrtn	mksIntegrationPointGetAutoStart (const mksIntegrationPoint ip, unsigned short *autostart)
	Function used to check the value of the autostart flag for the mksIntegrationPoint.
mksrtn	mksIntegrationPointGetHostname (const mksIntegrationPoint ip, char *buf, size_t len)
	Function used to retrieve the hostname of the given mksIntegrationPoint.
mksrtn	mksIntegrationPointGetPort (const mksIntegrationPoint ip, unsigned int *port)
	Function used to retrieve the port used by the mksIntegrationPoint.
mksrtn	mksIntegrationPointIsSecure (const mksIntegrationPoint ip, unsigned short *flag)
	Function used to check the value of the secure flag for the mksIntegrationPoint.
void	mksReleaseIntegrationPoint (mksIntegrationPoint ip)
	Function used to release an mksIntegrationPoint and all resources associated with it.
mksrtn	mksCreateMultiValue (mksMultiValue *mv)
	Function used to create a new mksMultiValue instance.
mksrtn	mksMultiValueAddValue (mksMultiValue mv, const wchar_t *value)
	Function used to add a new value to an mksMultiValue instance.
mksrtn	mksMultiValueAddMultiValue (mksMultiValue dest, const mksMultiValue src)
	Function used to copy the values of one mksMultiValue instance into another.
mksrtn	mksMultiValueGetSeparator (const mksMultiValue mv, wchar_t *separator)
	Function used to retrieve the separator used by the mksMultiValue instance.
mksrtn	mksMultiValueSetSeparator (mksMultiValue mv, const wchar_t separator)
	Function used to set the separator for an mksMultiValue instance.
void	mksReleaseMultiValue (mksMultiValue mv)
	Function used to release an mksMultiValue instance and all resources allocated by it.
mksrtn	mksCreateOptionList (mksOptionList *list)
	Function used to create and initialize a new mksOptionList instance.
mksrtn	mksOptionListAdd (mksOptionList list, const wchar_t *name, const wchar_t *value)
	Function used to add a new name/value option to an mksOptionList instance.
mksrtn	mksOptionListAddOptionList (mksOptionList dest, const mksOptionList src)
	Function used to add the data from one mksOptionList to another.
mksrtn	mksOptionListAddMultiValue (mksOptionList list, const wchar_t *name, const mksMultiValue value)
	Function to add a name/mksMultiValue option to an mksOptionList instance.
mksrtn	mksOptionListSize (const mksOptionList list, int *size)
	Function to retrieve the size of an mksOptionList instance.
mksrtn	mksOptionListGetFirst (mksOptionList list, wchar_t *name, size_t name_len, wchar_t *value, size_t value_len)
	Function used to retrieve the first name/value pair from an mksOptionList instance.
mksrtn	mksOptionListGetFirstString (mksOptionList list, wchar_t *buf, size_t len)
	Function used to retrieve the first name/value pair as a wchar_t * from an mksOptionList instance.
mksrtn	mksOptionListGetNext (mksOptionList list, wchar_t *name, size_t name_len, wchar_t *value, size_t value_len)
	Function used to retrieve the next name/value pair from an mksOptionList instance.
mksrtn	mksOptionListGetNextString (mksOptionList list, wchar_t *buf, size_t len)
	Function used to retrieve the next name/value pair as a wchar_t * from an mksOptionList instance.
void	mksReleaseOptionList (mksOptionList list)
	Function used to release an mksOptionList instance and all the resources allocated to it.
mksrtn	mksCreateSelectionList (mksSelectionList *list)
	Function used to create and initialize a new mksSelectionList instance.
mksrtn	mksSelectionListAdd (mksSelectionList list, const wchar_t *str)
	Function used to add a wchar_t * selection to an mksSelectionList.
mksrtn	mksSelectionListAddSelectionList (mksSelectionList dest, const mksSelectionList src)
	Function used to add the data from one mksSelectionList to another.
mksrtn	mksSelectionListGetFirst (mksSelectionList list, wchar_t *buf, size_t len)
	Function used to retrieve the first selection from an mksSelectionList.
mksrtn	mksSelectionListGetNext (mksSelectionList list, wchar_t *buf, size_t len)
	Function used to retrieve the next selection from an mksSelectionList.
mksrtn	mksSelectionListSize (const mksSelectionList list, int *size)
	Function used to retrieve the size of an mksSelectionList.
void	mksReleaseSelectionList (mksSelectionList list)
	Function used to release an mksSelectionList and all the resources associated with it.
mksrtn	mksCreateCmdRunner (mksCmdRunner *cr, mksSession session)
	Function used to create and initialize a new mksCmdRunner and associate it with an mksSession.
mksrtn	mksSessionGetAutoReconnect (const mksSession session, unsigned short *flag)
	Function used to retrieve the autoconnect flag from an mksSession.
mksrtn	mksSessionIsCommon (const mksSession session, unsigned short *flag)
	Function used to check to see if an mksSession is a common one or not.
mksIntegrationPoint	mksSessionGetIntegrationPoint (const mksSession session)
	Function used to retrieve the mksIntegrationPoint assocaited with an mksSession.
mksrtn	mksSessionSetAutoReconnect (mksSession session, const unsigned short flag)
	Function used set the auto reconnect flag for an mksSession instance.
mksrtn	mksSessionGetUsername (mksSession session, char *buf, size_t len)
	Function used to retrieve the session username from an mksSession.
mksrtn	mksSessionGetPassword (mksSession session, char *buf, size_t len)
	Function used to retrieve the session password from an mksSession.
void	mksReleaseSession (mksSession session)
	Function used to release an mksSession.
mksrtn	mksAPISetLocale (const char *locale)
	Function used to set the locale.

---

Define Documentation

#define AA   "aa"

Constant for the 'aa' Integrity application. Definition at line 26 of file mksCommand.h.

#define IM   "im"

Constant for the 'im' Integrity application. Definition at line 29 of file mksCommand.h.

#define INTEGRITY   "integrity"

Constant for the 'integrity' application. Definition at line 38 of file mksCommand.h.

#define RQ   "rq"

Constant for the 'rq' Integrity application. Definition at line 35 of file mksCommand.h.

#define SD   "sd"

Constant for the 'sd' Integrity application. Definition at line 44 of file mksCommand.h.

#define SI   "si"

Constant for the 'si' Integrity application. Definition at line 41 of file mksCommand.h.

#define TM   "tm"

Constant for the 'tm' Integrity application. Definition at line 32 of file mksCommand.h.

---

Typedef Documentation

typedef struct _mksCmdRunner* mksCmdRunner

typedef used for abstraction. Definition at line 68 of file mksCommand.h.

typedef struct _mksCommand* mksCommand

typedef used for clarity and simplicities sake. Definition at line 115 of file mksCommand.h.

typedef enum mksExecuteTypeEnum mksExecuteType

enum used to determine which type of response you would like to retrieve. INTERIM_NO_CACHE and INTERIM_CACHE are used to retrieve interim responses, which do not retrieve the entire response from the mksIntegrationPoint at once, but rather reads in the response in sections. INTERIM_NO_CACHE is a destructive type of execute in that it offers no random access, only serial access. Refer to the user documentation for a full description.

typedef struct _mksIntegrationPoint* mksIntegrationPoint

typedef used for abstraction. Definition at line 73 of file mksCommand.h.

typedef struct _mksMultiValue* mksMultiValue

typedef used for abstraction. Definition at line 78 of file mksCommand.h.

typedef struct _mksOptionList* mksOptionList

typedef used for abstraction. Definition at line 83 of file mksCommand.h.

typedef struct _mksSelectionList* mksSelectionList

typedef used for abstraction. Definition at line 88 of file mksCommand.h.

typedef struct _mksSession* mksSession

typedef used for abstraction. Definition at line 93 of file mksCommand.h.

---

Enumeration Type Documentation

enum mksExecuteTypeEnum

enum used to determine which type of response you would like to retrieve. INTERIM_NO_CACHE and INTERIM_CACHE are used to retrieve interim responses, which do not retrieve the entire response from the mksIntegrationPoint at once, but rather reads in the response in sections. INTERIM_NO_CACHE is a destructive type of execute in that it offers no random access, only serial access. Refer to the user documentation for a full description. Enumeration values: NO_INTERIM  Type used to retrieve a non-interim mksResponse. INTERIM_NO_CACHE  Type used to retrieve a interim mksResponse that does not cache mksSubRoutine or mksWorkItem instances. INTERIM_CACHE  Type used to retrieve a interim mksResponse that caches mksSubRoutine and mksWorkItem instances. Definition at line 55 of file mksCommand.h.

---

Function Documentation

mksrtn mksAPIInitialize (  const char *  logfile  )

Function used to initialize the API. This must be the first function called when starting to use the API to allow proper initialization of the internal logger, etc. Parameters: logfile  The filename to save the log data to. If this parameter is NULL, then the log data will not be saved to file. Returns: The error code of the function.

mksrtn mksAPISetLocale (  const char *  locale  )

Function used to set the locale. Parameters: locale  Locale specifier.

wchar_t* mksAPIStrError (  const mksrtn  error  )

Function used to retrieve a string represenation of a particular mksrtn error code. Parameters: error  The mksrtn to retrieve the string representation for. Returns: The wchar_t * message related to the error code.

mksrtn mksAPITerminate (  void   )

Function called after use of the Integrity API has been completed. This function will release any remaining system resources still in use and properly shut down the internal logging. It is vital that this function be called to properly release system resources before exiting an application. Returns: The error code of the function.

mksResponse mksCmdRunnerExecArr (  mksCmdRunner  cr, const wchar_t **  arr, const int  len, const mksExecuteType  type )

Function used to execute a command specified by the 'arr' array. Executing this function will reset the return value of the mksGetError() function. Parameters: cr  The mksCmdRunner to execute against. arr  The wchar_t * array containing the command to execute. len  The size of the wchar_t * array. type  The type of response to generate. Returns: The mksResponse generated by the function.

mksResponse mksCmdRunnerExecArrWithVendor (  mksCmdRunner  cr, const wchar_t **  arr, const int  len, const mksExecuteType  type, const char *  vendor )

Function used to execute a third party command specified by the 'arr' array. Executing this function will reset the return value of the mksGetError() function. Parameters: cr  The mksCmdRunner to execute against. arr  The wchar_t * array containing the command to execute. len  The size of the wchar_t * array. type  The type of response to generate. vendor  The third party vendor that created the command Returns: The mksResponse generated by the function.

mksResponse mksCmdRunnerExecCmd (  mksCmdRunner  cr, const mksCommand  cmd, const mksExecuteType  type )

Function used to execute a command contained within an mksCommand struct. Executing this function will reset the return value of the mksGetError() function. Parameters: cr  The mksCmdRunner to execute against. cmd  The mksCommand struct containing the command. type  The type of response to generate. Returns: The mksResponse generated by the function.

mksrtn mksCmdRunnerGetDefaultHostname (  const mksCmdRunner  cr, char *  buf, size_t  len )

Function used to retrieve the default hostname from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultImpersonationUser (  const mksCmdRunner  cr, char *  buf, size_t  len )

Function used to retrieve the default impersonation user from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultImpersonationUserWide (  const mksCmdRunner  cr, wchar_t *  buf, size_t  len )

Function used to retrieve the default impersonation user from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The wide char buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultPassword (  const mksCmdRunner  cr, char *  buf, size_t  len )

Function used to retrieve the default password from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultPasswordWide (  const mksCmdRunner  cr, wchar_t *  buf, size_t  len )

Function used to retrieve the default password from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The wide char buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultPort (  const mksCmdRunner  cr, unsigned int *  port )

Function used to retrieve the default port from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. port  The variable to store the default port into. A value of -1 means that no default was set. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultUsername (  const mksCmdRunner  cr, char *  buf, size_t  len )

Function used to retrieve the default username from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksCmdRunnerGetDefaultUsernameWide (  const mksCmdRunner  cr, wchar_t *  buf, size_t  len )

Function used to retrieve the default username from the mksCmdRunner. Parameters: cr  The mksCmdRunner to retrieve the default from. buf  The wide char buffer to store the data into. len  The size of the buffer. Returns: The error code of the function.

mksSession mksCmdRunnerGetSession (  const mksCmdRunner  cr  )

Function used to retrieve the mksSession associated with the given mksCmdRunner. This function will only return NULL if the mksCmdRunner passed in is NULL. Executing this function will reset the return value of the mksGetError() function. Parameters: cr  The mksCmdRunner to retrieve the mksSession from. Returns: The mksSession associated with the mksCmdRunner.

mksrtn mksCmdRunnerInterrupt (  mksCmdRunner  cr  )

Function used to interrupt an mksCmdRunner while it is executing a long running command or is in the middle of processing an interim response. If neither case is true for the given mksCmdRunner instance, then nothing occurs. Parameters: cr  The mksCmdRunner to interrupt. Returns: The error code of the function.

mksrtn mksCmdRunnerIsFinished (  const mksCmdRunner  cr, unsigned short *  flag )

Function used to check to see if the mksCmdRunner has completed executing a command or not. If the mksCmdRunner is using interim results, this command will not return true until the mksGetExit() function is called. Parameters: cr  The mksCmdRunner to check. flag  The variable used to hold the status of the mksCmdRunner. Returns: The error code of the function.

mksrtn mksCmdRunnerSetCallerID (  mksCmdRunner  cr, const char *  str )

Funtion used to set an identifier for the mksCmdRunner. This can be used by an integration to supply to the Integration Point an identifier that can be associated specifically with the command execution run. This will be also be inherited by an command execution internally derived from the calls made under ths command runner. Parameters: cr  The mksCmdRunner to set this identifier on. str  The value for the identifier. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultHostname (  mksCmdRunner  cr, const char *  str )

Function used to set the default hostname for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultImpersonationUser (  mksCmdRunner  cr, const char *  str )

Function used to set the default impersonation user for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultImpersonationUserWide (  mksCmdRunner  cr, const wchar_t *  str )

Function used to set the default impersonation user for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The wide char value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultPassword (  mksCmdRunner  cr, const char *  str )

Function used to set the default password for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultPasswordWide (  mksCmdRunner  cr, const wchar_t *  str )

Function used to set the default password for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The wide char value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultPort (  mksCmdRunner  cr, const unsigned int  port )

Function used to set the default port for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. port  The value for the default.

mksrtn mksCmdRunnerSetDefaultUsername (  mksCmdRunner  cr, const char *  str )

Function used to set the default username for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The value for the default. Returns: The error code of the function.

mksrtn mksCmdRunnerSetDefaultUsernameWide (  mksCmdRunner  cr, const wchar_t *  str )

Function used to set the default username for the mksCmdRunner. Parameters: cr  The mksCmdRunner to set the default on. str  The wide char value for the default. Returns: The error code of the function.

mksrtn mksCreateAPIConnector (  mksIntegrationPoint *  ip, const char *  host, const unsigned int  port, const unsigned short  secure, const unsigned short  apiMajorVersion, const unsigned short  apiMinorVersion )

Function used to create a generic mksIntegrationPoint to either an Integrity Client or an Integrity Server (both of which can be either local or remote). Through this function, an API version can be requested in the form of a major and minor numbers. This version would correspond to the version of the Integrition platform (for example MKS 2009 is version 4.10; major number 4, minor number 10) for which the integration was written and verified. By indicating the request version, should the Integrity platform be upgraded, the platform will at least be advised that the integration is still expecting API handling as per the requested version. Parameters: ip  A pointer to the mksIntegrationPoint constructed upon successful execution of this function. host  The host name of the mksIntegrationPoint. port  The port number of the mksIntegrationPoint. secure  Flag indicating if the connection should be secure (using SSL) or not. apiMajorVersion  The major number for the API version being requested. apiMinorVersion  The minor number for the API version being requested. Returns: The error code of the function.

mksrtn mksCreateCmdRunner (  mksCmdRunner *  cr, mksSession  session )

Function used to create and initialize a new mksCmdRunner and associate it with an mksSession. Parameters: cr  The variable containing an mksCmdRunner instance upon successful execution of this function. session  The mksSession to associate with the newly created mksCmdRunner. Returns: The error code of the function.

mksCommand mksCreateCommand (  void   )

Function used to create and initialize an mksCommand struct. Returns: The initialized mksCommand structure.

mksrtn mksCreateIntegrationPoint (  mksIntegrationPoint *  ip, const char *  host, const unsigned int  port, const unsigned short  secure )

Function used to create a generic mksIntegrationPoint to either an Integrity Client or an Integrity Server (both of which can be either local or remote). As of MKS 2009, this function is deprecated in favour of the function through which you would be asked to indicate the API version. Parameters: ip  A pointer to the mksIntegrationPoint constructed upon successful execution of this function. host  The host name of the mksIntegrationPoint. port  The port number of the mksIntegrationPoint. secure  Flag indicating if the connection should be secure (using SSL) or not. Returns: The error code of the function.

mksrtn mksCreateLocalAPIConnector (  mksIntegrationPoint *  ip, const unsigned short  apiMajorVersion, const unsigned short  apiMinorVersion, const unsigned short  autostart )

Function used to create an mksIntegrationPoint to the local Integrity Client. Through this function, an API version can be requested in the form of a major and minor numbers. This version would correspond to the version of the Integrition platform (for example MKS 2009 is version 4.10; major number 4, minor number 10) for which the integration was written and verified. By indicating the request version, should the Integrity platform be upgraded, the platform will at least be advised that the integration is still expecting API handling as per the requested version. Parameters: ip  A pointer to the mksIntegrationPoint constructed upon successful execution of this function. apiMajorVersion  The major number for the API version being requested. apiMinorVersion  The minor number for the API version being requested. autostart  Flag indicating if the Integrity Client should be started if it is not already running. Returns: The error code of the function.

mksrtn mksCreateLocalIntegrationPoint (  mksIntegrationPoint *  ip, const unsigned short  autostart )

Function used to create an mksIntegrationPoint to the local Integrity Client. As of MKS 2009, this function is deprecated in favour of the function through which you would be asked to indicate the API version. Parameters: ip  A pointer to the mksIntegrationPoint constructed upon successful execution of this function. autostart  Flag indicating if the Integrity Client should be started if it is not already running. Returns: The error code of the function.

mksrtn mksCreateMultiValue (  mksMultiValue *  mv  )

Function used to create a new mksMultiValue instance. Parameters: mv  A pointer to a newly created and initialized mksMultiValue instance. Returns: The error code of the function.

mksrtn mksCreateNamedSession (  mksSession *  session, const mksIntegrationPoint  ip, const char *  integrationAppID, const char *  user, const char *  pass )

Function used to create a named mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created. The name is to be defined by the integration application and will be used in Integrity as an identifier for the integration application. Parameters: session  A pointer to the newly constructed mksSession instance. ip  The mksIntegrationPoint to retrieve the mksSession from. integrationAppID  The integration application identifier. user  The session username. pass  The session password. Returns: The error code of the function.

mksrtn mksCreateNamedVersionedSession (  mksSession *  session, const mksIntegrationPoint  ip, const char *  integrationAppID, const unsigned short  apiMajorVersion, const unsigned short  apiMinorVersion, const char *  user, const char *  pass )

Function used to create a named versioned mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created. The name is to be defined by the integration application and will be used in Integrity as an identifier for the integration application. In addition, this function allow for the mksSession to be created with its own explicit API request version, independent of the one specified when the mksIntegrationPoint was created. (Refer to the docs on the creation of the mksIntegrationPoint for comments on the versioning). Parameters: session  A pointer to the newly constructed mksSession instance. ip  The mksIntegrationPoint to retrieve the mksSession from. integrationAppID  The integration application identifier. apiMajorVersion  The major number for the API version being requested. apiMinorVersion  The minor number for the API version being requested. user  The session username. pass  The session password. Returns: The error code of the function.

mksrtn mksCreateOptionList (  mksOptionList *  list  )

Function used to create and initialize a new mksOptionList instance. Parameters: list  The variable containing the newly created and initialized mksOptionList instance upon successful execution of this function. Returns: The error code of the function.

mksrtn mksCreateSelectionList (  mksSelectionList *  list  )

Function used to create and initialize a new mksSelectionList instance. Parameters: list  The list that is created by this function. Returns: The error code of the function.

mksrtn mksCreateSession (  mksSession *  session, const mksIntegrationPoint  ip, const char *  user, const char *  pass )

Function used to retrieve a non-common mksSession instance from the mksIntegrationPoint. By default, this mksSession will use the API request version as indicated when the mksIntegrationPoint was created. Parameters: session  A pointer to the newly constructed mksSession instance. ip  The mksIntegrationPoint to retrieve the mksSession from. user  The session username. pass  The session password. Returns: The error code of the function.

mksrtn mksCreateVersionedSession (  mksSession *  session, const mksIntegrationPoint  ip, const unsigned short  apiMajorVersion, const unsigned short  apiMinorVersion, const char *  user, const char *  pass )

Function used to retrieve a non-common mksSession instance from the mksIntegrationPoint. This function allow for the mksSession to be created with its own explicit API request version, independent of the one specified when the mksIntegrationPoint was created. (Refer to the docs on the creation of the mksIntegrationPoint for comments on the versioning). Parameters: session  A pointer to the newly constructed mksSession instance. ip  The mksIntegrationPoint to retrieve the mksSession from. apiMajorVersion  The major number for the API version being requested. apiMinorVersion  The minor number for the API version being requested. user  The session username. pass  The session password. Returns: The error code of the function.

mksrtn mksGetCommonSession (  mksSession *  session, const mksIntegrationPoint  ip )

Function used to retrieve the common mksSession instance from the mksIntegrationPoint. By default, the common mksSession will use the API request version as indicated when the mksIntegrationPoint was created. This function only makes sense if the mksIntegrationPoint is pointing at an Integrity Client (either local or remote). Parameters: session  A pointer to the newly constructed mksSession instance. ip  The mksIntegrationPoint to retrieve the mksSession from. Returns: The error code of the function.

mksrtn mksGetError (  void   )

For those functions that return objects, you can call mksGetError() to get the specific reason why the object wasn't returned. Returns: The error code of the function.

mksrtn mksIntegrationPointGetAutoStart (  const mksIntegrationPoint  ip, unsigned short *  autostart )

Function used to check the value of the autostart flag for the mksIntegrationPoint. The autostart flag is only set when the mksIntegrationPoint was created by the mksCreateLocalIntegrationPoint() function. Parameters: ip  The mksIntegationPoint to check the flag. autostart  A variable containing the status of the autostart flag. Returns: The error code of the function.

mksrtn mksIntegrationPointGetHostname (  const mksIntegrationPoint  ip, char *  buf, size_t  len )

Function used to retrieve the hostname of the given mksIntegrationPoint. Parameters: ip  The mksIntegrationPoint to retrieve the hostname from. buf  The buffer that the hostname will be copied into. len  The size of the given buffer. Returns: The error code of the function.

mksrtn mksIntegrationPointGetPort (  const mksIntegrationPoint  ip, unsigned int *  port )

Function used to retrieve the port used by the mksIntegrationPoint. If the mksIntegrationPoint was created using the mksCreateLocalIntegrationPoint() function, then the port will return 0 until at least one command has been executed. Parameters: ip  The mksIntegrationPoint to retrieve the port from. port  A variable containing the value of the port upon successful execution of this function. Returns: The error code of the function.

mksrtn mksIntegrationPointIsSecure (  const mksIntegrationPoint  ip, unsigned short *  flag )

Function used to check the value of the secure flag for the mksIntegrationPoint. Parameters: ip  The mksIntegationPoint to check the flag. flag  A variable containing the status of the secure flag. Returns: The error code of the function.

mksrtn mksMultiValueAddMultiValue (  mksMultiValue  dest, const mksMultiValue  src )

Function used to copy the values of one mksMultiValue instance into another. Parameters: dest  The mksMultiValue instance to copy values into. src  The mksMultiValue instance to copy values from. Returns: The error code of the function.

mksrtn mksMultiValueAddValue (  mksMultiValue  mv, const wchar_t *  value )

Function used to add a new value to an mksMultiValue instance. Parameters: mv  The mksMultiValue to add the value to. value  The value to add to the mksMultiValue. Returns: The error code of the function.

mksrtn mksMultiValueGetSeparator (  const mksMultiValue  mv, wchar_t *  separator )

Function used to retrieve the separator used by the mksMultiValue instance. Parameters: mv  The mksMultiValue to retrieve the separator from. separator  The variable containing the separator upon successful completion of this function. Returns: The error code of the function.

mksrtn mksMultiValueSetSeparator (  mksMultiValue  mv, const wchar_t  separator )

Function used to set the separator for an mksMultiValue instance. The separator is used each time a new value is added to the mksMultiValue instance, so calling this function multiple times on the same mksMultiValue instance will result in having multiple separators in the mksMultiValue instance. Parameters: mv  The mksMultiValue to set the separator for. separator  The separator to set. Returns: The error code of the function.

mksrtn mksOptionListAdd (  mksOptionList  list, const wchar_t *  name, const wchar_t *  value )

Function used to add a new name/value option to an mksOptionList instance. Parameters: list  The mksOptionList instance to add the option to. name  The name of the option. value  The value of the option. Can be NULL. Returns: The error code of the function.

mksrtn mksOptionListAddMultiValue (  mksOptionList  list, const wchar_t *  name, const mksMultiValue  value )

Function to add a name/mksMultiValue option to an mksOptionList instance. Parameters: list  The mksOptionList instance to add the option to. name  The name of the option. value  The mksMultiValue instance to add to the mksOptionList. Returns: The error code of the function.

mksrtn mksOptionListAddOptionList (  mksOptionList  dest, const mksOptionList  src )

Function used to add the data from one mksOptionList to another. Parameters: dest  The mksOptionList to add the data from the other mksOptionList into. src  The mksOptionList to copy the data from. Returns: The error code of the function.

mksrtn mksOptionListGetFirst (  mksOptionList  list, wchar_t *  name, size_t  name_len, wchar_t *  value, size_t  value_len )

Function used to retrieve the first name/value pair from an mksOptionList instance. Parameters: list  The mksOptionList to retrieve the name/value pair from. name  The buffer to populate with the name. name_len  The size of the name buffer. value  The buffer to populate with the value. value_len  The size of the value buffer. Returns: The error code of the function.

mksrtn mksOptionListGetFirstString (  mksOptionList  list, wchar_t *  buf, size_t  len )

Function used to retrieve the first name/value pair as a wchar_t * from an mksOptionList instance. The string representation will be of the form: <prefix>name<separator>value where the prefix is either - or -- and the separator is either a space or an equals sign, depending on the name/value pair. Parameters: list  The mksOptionList to retrieve the wchar_t * representation of the name/value pair from. buf  The buffer to populate. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksOptionListGetNext (  mksOptionList  list, wchar_t *  name, size_t  name_len, wchar_t *  value, size_t  value_len )

Function used to retrieve the next name/value pair from an mksOptionList instance. Parameters: list  The mksOptionList to retrieve the name/value pair from. name  The buffer to populate with the name. name_len  The size of the name buffer. value  The buffer to populate with the value. value_len  The size of the value buffer. Returns: The error code of the function.

mksrtn mksOptionListGetNextString (  mksOptionList  list, wchar_t *  buf, size_t  len )

Function used to retrieve the next name/value pair as a wchar_t * from an mksOptionList instance. The string representation will be of the form: <prefix>name<separator>value where the prefix is either - or -- and the separator is either a space or an equals sign, depending on the name/value pair. Parameters: list  The mksOptionList to retrieve the wchar_t * representation of the name/value pair from. buf  The buffer to populate. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksOptionListSize (  const mksOptionList  list, int *  size )

Function to retrieve the size of an mksOptionList instance. Parameters: list  The mksOptionList to retrieve the size from. size  The variable containing the size of the given mksOptionList instance upon successful execution of the function. Returns: The error code of the function.

void mksReleaseCmdRunner (  mksCmdRunner  cr  )

Function used to release the mksCmdRunner. Releasing an mksCmdRunner will interrupt any interim result processing that may be in progress. Parameters: cr  The mksCmdRunner to release.

void mksReleaseCommand (  mksCommand  cmd  )

Function used to release the fields in the mksCommand struct. It will release the cmd structure as well. Parameters: cmd  The mksCommand instance to free

void mksReleaseIntegrationPoint (  mksIntegrationPoint  ip  )

Function used to release an mksIntegrationPoint and all resources associated with it. Releasing an mksIntegrationPoint will also release any mksSessions associated with it. Parameters: ip  The mksIntegrationPoint to release.

void mksReleaseMultiValue (  mksMultiValue  mv  )

Function used to release an mksMultiValue instance and all resources allocated by it. Parameters: mv  The mksMultiValue instance to release.

void mksReleaseOptionList (  mksOptionList  list  )

Function used to release an mksOptionList instance and all the resources allocated to it. Parameters: list  The mksOptionList to release.

void mksReleaseSelectionList (  mksSelectionList  list  )

Function used to release an mksSelectionList and all the resources associated with it. Parameters: list  The mksSelectionList to release.

void mksReleaseSession (  mksSession  session  )

Function used to release an mksSession. When the mksSession is released, all mksCmdRunner instances associated with the mksSession will also be released. Parameters: session  The mksSession to release.

mksrtn mksSelectionListAdd (  mksSelectionList  list, const wchar_t *  str )

Function used to add a wchar_t * selection to an mksSelectionList. Parameters: list  The mksSelectionList to add the selection to. str  The wchar_t * selection to add. Returns: The error code of the function.

mksrtn mksSelectionListAddSelectionList (  mksSelectionList  dest, const mksSelectionList  src )

Function used to add the data from one mksSelectionList to another. Parameters: dest  The mksSelectionList to add the data from the other mksSelectionList into. src  The mksSelectionList to copy the data from. Returns: The error code of the function.

mksrtn mksSelectionListGetFirst (  mksSelectionList  list, wchar_t *  buf, size_t  len )

Function used to retrieve the first selection from an mksSelectionList. Parameters: list  The mksSelectionList to retrieve the first selection from. buf  The buffer to copy the first element of the mksSelectionList into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksSelectionListGetNext (  mksSelectionList  list, wchar_t *  buf, size_t  len )

Function used to retrieve the next selection from an mksSelectionList. Parameters: list  The mksSelectionList to retrieve the next selection from. buf  The buffer to copy the first element of the mksSelectionList into. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksSelectionListSize (  const mksSelectionList  list, int *  size )

Function used to retrieve the size of an mksSelectionList. Parameters: list  The mksSelectionList to retrieve the size of. size  The variable that will contain the size of the list upon successful execution of this function. Returns: The error code of the function.

mksrtn mksSessionGetAutoReconnect (  const mksSession  session, unsigned short *  flag )

Function used to retrieve the autoconnect flag from an mksSession. Parameters: session  The mksSession to retrieve the flag from. flag  The variable containing the value of the autostart flag upon successful execution of the function. Returns: The error code of the function.

mksIntegrationPoint mksSessionGetIntegrationPoint (  const mksSession  session  )

Function used to retrieve the mksIntegrationPoint assocaited with an mksSession. Parameters: session  The mksSession to retrieve the mksIntegrationPoint from. Returns: The mksIntegrationPoint associated with the mksSession.

mksrtn mksSessionGetPassword (  mksSession  session, char *  buf, size_t  len )

Function used to retrieve the session password from an mksSession. Parameters: session  The mksSession to retrieve the session password from. buf  The buffer to copy the session password to. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksSessionGetUsername (  mksSession  session, char *  buf, size_t  len )

Function used to retrieve the session username from an mksSession. Parameters: session  The mksSession to retrieve the session username from. buf  The buffer to copy the session username to. len  The size of the buffer. Returns: The error code of the function.

mksrtn mksSessionIsCommon (  const mksSession  session, unsigned short *  flag )

Function used to check to see if an mksSession is a common one or not. Parameters: session  The mksSession to retrieve the flag from. flag  The variable containing the value of the common flag upon successful execution of the function. Returns: The error code of the function.

mksrtn mksSessionSetAutoReconnect (  mksSession  session, const unsigned short  flag )

Function used set the auto reconnect flag for an mksSession instance. Parameters: session  The mksSession instance to set the auto reconnect flag for. flag  The value of the auto reconnect flag to set. Returns: The error code of the function.

---

_{Any use, disclosure, reproduction or modification of this Software other than as expressly authorized in writing by PTC is strictly prohibited.}