Class WMX3Api

Defined in File WMX3Api.h

Class Documentation

class WMX3Api

This class contains core functions.

Public Functions

WMX3Api(): Default constructor for this class.

~WMX3Api(): Destructor for this class.

bool IsDeviceValid()

Return TRUE if this class object has access to a device, and FALSE otherwise. A device is required to execute most functions in this class. If this function returns FALSE, a device can be created by calling the CreateDevice function.

WMX3APIFUNC StartEngine(const char *path, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Start the WMX3 engine without creating a device.

This function can starts the WMX3 engine without creating a device. Typically, this function does not need to be called, as the engine is automatically started when the first device is created with the CreateDevice function.

Remark

Scenarios in which the user might use this function include the following:

The architecture of the user application requires the engine to be started independently before creating any devices.
The user has closed the engine using the StopEngine function while some devices remain open. In this case, calling this function will start the engine and cause the link to existing devices to be restored so that they may call API functions again.

Unlike most API functions, this function can be called successfully without creating a device with CreateDevice.

This function is blocking, and may take several seconds or more before it returns a value.

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait for the engine to start before returning. If no value is specified or 0 is specified, this function will block until the engine process starts, but will return before the engine fully initializes. If another function is called before the engine is fully initialized, an error will be returned. The Engine State status obtained by GetStatus can be checked to see the engine has been initialized (this status will contain Idle while the engine has not fully initialized). If a nonzero value is specified, this function will wait until the engine starts or the specified amount of time elapses. If the engine has not started after waiting for the specified amount of time, the EngineNotStartedInSpecifiedTime error is returned.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC StartEngine(const wchar_t *path, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Start the WMX3 engine without creating a device.

This function is a variation of StartEngine that accepts a wchar_t string for the file path. Use this function when using Unicode character sets.

Remark

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait for the engine to start before returning. If no value is specified or 0 is specified, this function will block until the engine process starts, but will return before the engine fully initializes. If another function is called before the engine is fully initialized, an error will be returned. The Engine State status obtained by GetStatus can be checked to see the engine has been initialized (this status will contain Idle while the engine has not fully initialized). If a nonzero value is specified, this function will wait until the engine starts or the specified amount of time elapses. If the engine has not started after waiting for the specified amount of time, the EngineNotStartedInSpecifiedTime error is returned.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC RestartEngine(const char *path, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Stop the currently running WMX3 engine and then restart the WMX3 engine.

This function stops the currently running WMX3 engine and then restarts the WMX3 engine.

Remark

This function is equivalent to calling the StopEngine function, waiting until the engine has closed, and then calling the StartEngine function.

When the engine is restarted, all data will be initialized as if the engine is started for the first time. This includes all parameter data, which will be reset to their default values, and all I/O and user memory data, which will be cleared. All dynamically allocated buffer memory will be released (see Function Calls Related to Memory Allocation).

Scenarios in which the user might use this function include the following:

The user wants to change the loaded modules or other engine options without closing all devices. By calling this function, the engine can be restarted with different loaded modules or other engine options. Any existing devices will automatically reconnect with the engine after it is restarted.

Unlike most API functions, this function can be called successfully without creating a device with CreateDevice.

This function is blocking, and may take several seconds or more before it returns a value.

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait for the engine to start before returning. If no value is specified or 0 is specified, this function will block until the engine process starts, but will return before the engine fully initializes. If another function is called before the engine is fully initialized, an error will be returned. The Engine State status obtained by GetStatus can be checked to see the engine has been initialized (this status will contain Idle while the engine has not fully initialized). If a nonzero value is specified, this function will wait until the engine starts or the specified amount of time elapses. If the engine has not started after waiting for the specified amount of time, the EngineNotStartedInSpecifiedTime error is returned.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC RestartEngine(const wchar_t *path, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Stop the currently running WMX3 engine and then restart the WMX3 engine.

This function is a variation of RestartEngine that accepts a wchar_t string for the file path. Use this function when using Unicode character sets.

Remark

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait for the engine to start before returning. If no value is specified or 0 is specified, this function will block until the engine process starts, but will return before the engine fully initializes. If another function is called before the engine is fully initialized, an error will be returned. The Engine State status obtained by GetStatus can be checked to see the engine has been initialized (this status will contain Idle while the engine has not fully initialized). If a nonzero value is specified, this function will wait until the engine starts or the specified amount of time elapses. If the engine has not started after waiting for the specified amount of time, the EngineNotStartedInSpecifiedTime error is returned.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC StopEngine(unsigned int waitTimeMilliseconds = 0)

Stop the currently running WMX3 engine.

This function stops the WMX3 engine, regardless of whether there were any open devices left. Typically, this function does not need to be called, as the engine is automatically stopped when the last device is closed with the CloseDevice function.

Remark

When the engine is restarted with the StartEngine function, all data will be initialized as if the engine is started for the first time. This includes all parameter data, which will be reset to their default values, and all I/O and user memory data, which will be cleared. When the engine is stopped, all dynamically allocated buffer memory will be released (see Function Calls Related to Memory Allocation).

Scenarios in which the user might use this function include the following:

The user wants to change the loaded modules or other engine options without closing all devices. By calling this function, waiting until the engine stops, and then starting the engine again with the StartEngine function, the loaded modules or other engine options can be changed. Any existing devices will automatically reconnect with the engine after it is restarted.

Unlike most API functions, this function can be called successfully without creating a device with CreateDevice.

This function is blocking, and may take several seconds or more before it returns a value.

Parameters:: waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait for the engine to stop before returning. If no value is specified or 0 is specified, this function will block until a stop signal is sent to the engine process, but will return without checking if the engine process has stopped. If a nonzero value is specified, this function will wait until the engine process has stopped before returning.

WMX3APIFUNC CreateDevice(const char *path, DeviceType::T type = DeviceType::T::DeviceTypeNormal, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Create a device to interface with the WMX3 engine.

Each WMX3Api object must call this function first to establish an interface with the WMX3 engine before calling any API function (with a few exceptions). After this function succeeds and returns None, other API functions can be called.

Remark

A pointer to a WMX3Api object must be passed to the constructor of classes that contain the API functions of each module. Before calling any API functions contained in that class, the CreateDevice function must be called from the passed WMX3Api object. The CreateDevice function can be called before or after passing the WMX3Api object to the constructor.

If this function is not called, or if this function fails, all other API functions (with a few exceptions) will return the DeviceIsNull error.

Once a device is succesfully created for a WMX3Api object, it will not need to call this function again unless the device is closed with the CloseDevice function).

Each thread in the user application must instantiate a separate WMX3Api object and call CreateDevice. If multiple threads call API functions using the same device, there may be a delay when calling API functions, and some API functions such as Wait will not operate correctly due to shared resources.

If the WMX3 engine process is not running when this function is called, the WMX3 engine process will be started.

Up to maxDevices devices may exist at the same time, and may independently communicate with the WMX3 engine. Therefore, the user application may call WMX3 library API functions from up to maxDevices threads. Attempting to create more than maxDevices devices will cause this API function to return the ReachMaxChannelNumber error.

This function is blocking, and may take several seconds or more before it returns a value.

See also

Devices

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
type – [in] An optional argument that specifies the type of device to create. This determines the method by which the device executes API functions. Also see Device Types.
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait after the device is created to verify that the engine is in a normal state. If no value is specified or 0 is specified, this function will not verify whether the engine is a normal state. If a value greater than 0 is specified, this function will continue to block after the device is created to communicate with the engine and verify that the engine is in a normal state. This function returns when the engine is confirmed to be in a normal state or when the specified time elapses. If this function cannot verify that the engine is in a normal state after waiting for the specified time, it will return the SystemInitializationNotDone error.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC CreateDevice(const wchar_t *path, DeviceType::T type = DeviceType::T::DeviceTypeNormal, unsigned int waitTimeMilliseconds = 0, int core = -1, DWORD_PTR affinityMask = 0)

Create a device to interface with the WMX3 engine.

This function is a variation of CreateDevice that accepts a wchar_t array for the file path string. Use this function when using Unicode character sets.

Remark

See also

Devices

Parameters:

path – [in] The full path of the directory that contains the WMX3 engine (WMX3Engine.rtss).
type – [in] An optional argument that specifies the type of device to create. This determines the method by which the device executes API functions.
waitTimeMilliseconds – [in] An optional argument that specifies the amount of time to wait after the device is created to verify that the engine is in a normal state. If no value is specified or 0 is specified, this function will not verify whether the engine is a normal state. If a value greater than 0 is specified, this function will continue to block after the device is created to communicate with the engine and verify that the engine is in a normal state. This function returns when the engine is confirmed to be in a normal state or when the specified time elapses. If this function cannot verify that the engine is in a normal state after waiting for the specified time, it will return the SystemInitializationNotDone error.
core – [in] An optional argument that sets the CPU core to run the engine on. The specified core must be assigned to the RTX operating system. If the specified core does not exist or is not assigned to the RTX operating system, the default core will be used instead. This argument will have no effect if the engine is already running when this function is called.
affinityMask – [in] An optional argument that can be used to specify more than one CPU core to run the engine on. For example, to run the engine on CPU cores 0, 1, and 2, the affinity mask should be set to (1 << 0) | (1 << 1) | (1 << 2). The specified cores must be assigned to the RTX operating system. If both “core” and “affinityMask” are specified, the engine will run on all cores specified in either of these values. This argument will have no effect if the engine is already running when this function is called.

WMX3APIFUNC CloseDevice(bool exitNoDev = true)

Close a device.

This function closes the device used to interface with the WMX3 engine that has been created with the CreateDevice function. Each object of the WMX3Api class that has successfully created a device must call the CloseDevice function before the user application exits or the object is deleted.

Remark

The WMX3 engine automatically exits when all devices have been closed with this function. If any devices are not closed when the user application exits, the WMX3 engine will remain running. (The engine will close if the Watchdog timer runs out.)

This function is blocking. When this function is called, execution will return to the calling thread only after the device is closed, or when the time out period elapses.

See also

Devices

Parameters:: exitNoDev – [in] If set to true, the engine will exit if the closed device is the last open device (excluding DeviceTypeExitWOCnt devices). If set to false, the engine will not exit even if the closed device is the last open device. This parameter will be set to true if not specified.

WMX3APIFUNC GetDeviceID(int *id)

Get the device ID number of the device.

This function returns the device ID number of the device.

Remark

All running devices will have unique device ID numbers.

Device ID numbers of devices that have been closed with CloseDevice are freed, and may be assigned to devices later created by CreateDevice.

Parameters:: id – [out] A pointer to an int that will contain the ID number of the device.

WMX3APIFUNC AutoQuitWithoutActiveDev(bool quit)

Configure the engine to automatically quit or not automatically quit when the last device is closed by a watchdog time out.

This function configures the engine to automatically quit or not automatically quit when the last device is closed by a watchdog time out.

Remark

By default, the engine is configured to automatically quit when the last device is closed by a watchdog time out.

See also

SetWatchdog

Parameters:: quit – [in] A flag signifying whether to automatically stop the engine when the last device is closed. If set to TRUE, the engine will automatically stop. If set to FALSE, the engine will not automatically stop.

WMX3APIFUNC SetWatchdog(unsigned int watchdog)

Set the watchdog time out period for the device that called this function.

This function sets the watchdog time out period for the device that called this function. Even if this function is not called, a watchdog timer is enabled for each device using the default time out period. If the process that created the device is closed without closing the device, the device will be automatically closed after the watchdog time out period elapses.

Remark

See also

Overview

Parameters:: watchdog – [in] The watchdog time out period, in milliseconds.

WMX3APIFUNC SetWatchdog(int deviceId, unsigned int watchdog)

Set the watchdog time out period for a specific device.

This function sets the watchdog time out period for the device with the specified ID.

Remark

See also

Overview

Parameters:

watchdog – [in] The watchdog time out period, in milliseconds.
deviceId – [in] The device ID of the device.

WMX3APIFUNC GetWatchdog(unsigned int *watchdog, unsigned int *watchdogCount = NULL)

Get the watchdog time out period and the current watchdog count.

This function obtains the current watchdog time out period and watchdog count of the device that called this function.

Remark

Parameters:

watchdog – [out] The watchdog time out period set for this device, in milliseconds. If this value is 0, the device has no watchdog.
watchdogCount – [out] An optional argument that will retrieve the current watchdog count for this device. This is the number of milliseconds that have elapsed since the watchdog thread last reported that the device is operating normally.

WMX3APIFUNC ResetWatchdogTimer()

Reset the watchdog count of a device.

This function resets the watchdog count value of the device that called this function so that it is considered to be alive until the watchdog time out period elapses again. Normally, this function does not need to be called, as the watchdog thread that is automatically started when a device is created will periodically reset the watchdog count.

Remark

WMX3APIFUNC SetStatistic(bool enable)

Configure a device to collect API execution statistics data.

This function configures a device to collect or not collect API execution statistics data.

Remark

See also

GetStatistic

Parameters:: enable – [in] Whether to enable device statistics collection.

WMX3APIFUNC GetStatistic(DeviceStatistics *statistics)

Read the currently collected API execution statistics data.

This function obtains the currently collected API execution statistics data for a device. The device must be first configured to collect this data using the SetStatistic function.

Remark

This data is collected as API functions are executed through this device. The GetStatistic function can be used to read the collected data. See the DeviceStatistics class for additional information regarding the data that is collected.

This data is not collected for API functions that are not executed by API process threads. See Function Calls for Special Processing for a list of these functions.

This data is collected for API functions when they are appended to the API buffer but not when they are executed from the API buffer (see API Buffer).

See also

SetStatistic

Parameters:: statistics – [out] A pointer to a DeviceStatistics object that will contain the collected statistics data.

WMX3APIFUNC SetInterruptId(unsigned int interruptId)

Set the interrupt (cyclic handler) associated with the calling device.

This function sets the interrupt (cyclic handler) to associate with the calling device.

Remark

After calling the CreateDevice function to create a device, that device can be associated to a particular interrupt by calling this function. A few functions are affected by the interrupt associated with the calling device. Other than these functions, the interrupt associated with the calling device has no effect on the operation of the device. See Function Calls Affected by Interrupts for additional information.

A newly created device is by default associated with interrupt 0.

The interrupt ID must be at least 0 and less than maxInterrupts.

Parameters:: interruptId – [in] The interrupt to associate with the calling device.

WMX3APIFUNC GetInterruptId(unsigned int *interruptId)

Get the interrupt (cyclic handler) associated with the calling device.

This function obtains the ID of the interrupt (cyclic handler) associated with the calling device. This interrupt is set using the SetInterruptId function.

Remark

Parameters:: interruptId – [out] A pointer to an unsigned int that will contain the interrupt associated with the calling device.

WMX3APIFUNC StartCommunication(unsigned int waitTimeMilliseconds = 0)

Start communication with the servo network.

This function must be called before performing any other functions that require communication with the servo network.

Remark

To check if communication with the servo network can be started, call the GetStatus API function and check the Engine State variable. If this value is equal to Idle, communication cannot be started yet and calling this function will have no effect. If this value is equal to Running, communication can be started with this function.

Even if Engine State is equal to Running, some additional time is required to establish a link with the network. Calling this function at this time will cause it to return the StartCommunicationError. If this occurs, call this function after waiting for a few seconds.

To check if communication with the servo network has been successfully established, again call the GetStatus API function and check the Engine State variable. If Engine State is equal to Communicating, communication is working.

This function is blocking. When this function is called, execution will return only when a network communication request is initiated, or when the initiation of the network communication request times out. Note that the engine status will not immediately change to Communicating after the network communication request is initiated. Even after this function returns, it may be necessary to wait for several seconds before GetStatus returns the Communicating status. If a value is specified for the waitTimeMilliseconds parameter, this function will wait until the engine status changes to Communicating or the specified time out period elapses before returning.

Functions that require communication with the servo network will return errors unless they are executed after the Engine State becomes Communicating.

Parameters:: waitTimeMilliseconds – The amount of time to wait for communication to be established before returning. If this argument is set to 0, or it is not specified, this function will send a signal to start communication but may return before communication is completely established. If this argument is set to a nonzero value, the function will block and not return until communication is established or the waitTimeMilliseconds time elapses. In this case, an error will be returned if waitTimeMilliseconds elapses before communication is established. If an error is returned this way, the signal to start communication will remain set and communication may still become established a few moments later.

WMX3APIFUNC StopCommunication(unsigned int waitTimeMilliseconds = 0)

Stop communication with the servo network.

This function can be called after establishing communication with the servo network using the StartCommunication function. This function will end communication with the servo network. To check if communication with the servo network has been successfully stopped, call the GetStatus API function and check the Engine State variable. If the Engine State is no longer Communicating, communication has been stopped (the Engine State will normally be Running at this point).

Remark

Note that the Engine State will not immediately change to Running immediately after this function is called. Even after this function returns, it may be necessary to wait for several seconds before GetStatus returns the Running engine status. If a value is specified for the waitTimeMilliseconds parameter, this function will wait until the engine status changes to Running or the specified time out period elapses before returning.

No function that requires communication with the servo network may be executed after communication is stopped. StartCommunication may be called again to reestablish communication with the servo network.

Parameters:: waitTimeMilliseconds – The amount of time to wait for communication to be stopped before returning. If this argument is set to 0, or it is not specified, this function will send a signal to stop communication but may return before communication is completely stopped. If this argument is set to a nonzero value, the function will block and not return until communication is stopped or the waitTimeMilliseconds time elapses. In this case, an error will be returned if waitTimeMilliseconds elapses before communication is stopped. If an error is returned this way, the signal to stop communication will remain set and communication may still become established a few moments later.

WMX3APIFUNC GetModulesInfo(ModulesInfoA *modules)

Obtain information of the modules that are loaded by the engine.

This function obtains the information of the modules that are loaded by the engine. The engine can execute API functions in a module library only if the corresponding module has been loaded. See ModulesInfoA for additional information regarding the module data that can be obtained.

Remark

Parameters:: modules – [out] A pointer to a ModulesInfoA object that will contain the information of the modules that are loaded by the engine.

WMX3APIFUNC GetModulesInfo(ModulesInfoW *modules)

Obtain information of the modules that are loaded by the engine.

This function is a variation of GetModulesInfo that obtains certain module information as wchar_t strings instead of char strings. Use this function when using Unicode character sets.

Remark

Parameters:: modules – [out] A pointer to a ModulesInfoW object that will contain the information of the modules that are loaded by the engine.

WMX3APIFUNC GetModuleInfo(int moduleId, ModuleInfoA *module)

Obtain information of a single module that is loaded by the engine.

This function obtains the information of a single module that is loaded by the engine.

Remark

If the module with the specified moduleId is not loaded, a ModuleIsNotLoaded error is returned.

Parameters:

moduleId – [out] The unique id number of the module to check.
module – [out] A pointer to a ModuleInfoA object that will contain the information of the specified module, if it is loaded by the engine.

WMX3APIFUNC GetModuleInfo(int moduleId, ModuleInfoW *module)

Obtain information of a single module that is loaded by the engine.

This function is a variation of GetModuleInfo that obtains certain module information as wchar_t strings instead of char strings. Use this function when using Unicode character sets.

Remark

Parameters:

moduleId – [out] The unique id number of the module to check.
module – [out] A pointer to a ModuleInfoW object that will contain the information of the specified module, if it is loaded by the engine.

WMX3APIFUNC GetEngineStatus(EngineStatus *status)

Obtain the status of the engine.

This funtion obtains the status of the engine.

Remark

Parameters:: status – [out] A pointer to a EngineStatus object that will contain the engine status.

WMX3APIFUNC GetAllDevices(DevicesInfoA *devices)

Obtain information of all existing devices.

This function obtains the information of all existing devices. This includes the number of currently existing devices and the ID and name of each device.

Remark

This function can be used to verify that all other devices have closed.

Parameters:: devices – [out] A pointer to a DevicesInfoA object that will contain the information of all existing devices.

WMX3APIFUNC GetAllDevices(DevicesInfoW *devices)

Obtain information of all existing devices.

This function is a variation of GetAllDevices that obtains certain device information as wchar_t strings instead of char strings. Use this function when using Unicode character sets.

Remark

Parameters:: devices – [out] A pointer to a DevicesInfoW object that will contain the information of all existing devices.

WMX3APIFUNC SetDeviceName(const char *name)

Set the name of this device.

This function sets the name of the device calling this function. The device name has no effect on the operation of the device, except that it makes the device easier to identify when using functions such as GetAllDevices.

Remark

Parameters:: name – [in] A char array that contains the name of the device as a null-terminated string. The array must not be longer than maxDeviceName characters, or else the name will be truncated.

WMX3APIFUNC SetDeviceName(const wchar_t *name)

Set the name of this device.

This function is a variation of SetDeviceName that sets the device name as a wchar_t string instead of a char string. Use this function when using Unicode character sets.

Remark

Parameters:: name – [in] A wchar_t array that contains the name of the device as a null-terminated string. The array must not be longer than maxDeviceName characters, or else the name will be truncated.

WMX3APIFUNC GetDeviceName(char *nameBuf, unsigned int bufSize)

Get the name of this device.

This function gets the name of the device calling this function. The name of the device can be set using the SetDeviceName function.

Remark

The default name of a device before calling the SetDeviceName function is blank.

Parameters:

nameBuf – [out] A char array that will contain the name of the device as a null-terminated string. The array must have space to store at least maxDeviceName characters.
bufSize – [in] The size of the char array passed to the nameBuf argument.

WMX3APIFUNC GetDeviceName(wchar_t *nameBuf, unsigned int bufSize)

Get the name of this device.

This function is a variation of GetDeviceName that gets the device name as a wchar_t string instead of a char string. Use this function when using Unicode character sets.

Remark

Parameters:

nameBuf – [out] A wchar_t array that will contain the name of the device as a null-terminated string. The array must have space to store at least maxDeviceName characters.
bufSize – [in] The size of the wchar_t array passed to the nameBuf argument.

WMX3APIFUNC SetDeviceWaitEvent(int errCode)

Reserved.

WMX3APIFUNC ResetDeviceWaitEvent()

Reserved.

WMX3APIFUNC WaitForDeviceWaitEvent(unsigned int waitTime, int *errCode)

Reserved.

WMX3APIFUNC SetModuleSuspend(ModuleSuspend *suspend)

Set whether to suspend loading specific platform modules when starting communication.

This function configures the engine to suspend loading specific platform modules when communication is started.

Remark

Platform modules for which the suspend setting is set to 1 are not loaded.

Platform modules for which the suspend setting is set to 0 are loaded.

One use of this function is to dynamically switch between loading the simulator module and non-simulator platform modules without stopping the engine or modifying configuration files.

The following modules may be suspended by this function:

Platform modules that are disabled in the configuration file will not be loaded, regardless of its suspend setting.

The applied suspend settings take effect the next time communication is started.

Parameters:: suspend – [in] A pointer to a ModuleSuspend object that contains the suspend setting for each platform module.

WMX3APIFUNC GetModuleSuspend(ModuleSuspend *suspend)

Get the settings of whether to suspend loading specific platform modules when starting communication.

This function reads the suspend setting of each platform module.

Remark

Suspend settings are checked by the engine whenever communication is started. Platform modules for which the suspend setting is 1 will not be loaded.

Parameters:: suspend – [out] A pointer to a ModuleSuspend object that will contain the suspend setting for each platform module.

WMX3APIFUNC AbortModuleSuspend()

Clear all settings of whether to suspend loading specific platform modules when starting communication.

This function clears all suspend settings that have been set by SetModuleSuspend.

Remark

All platform modules that are enabled in the configuration file will be loaded by the engine the next time communication is started.

WMX3APIFUNC SleepAtEngine(unsigned long microSecond)

Pauses execution of the current thread until the specified timeout interval elapses.

This function suspends execution of the current thread until the specified timeout interval elapses.

Remark

The timeout interval must be set to a value greater than or equal to the minimum timer period of the system on which the engine is running.

If the specified timeout interval is below the minimum timer period, no error is returned and the thread pauses execution for at least the minimum timer period.

Even if the timeout interval is greater than or equal to the minimum timer period, the thread may pause for a minimum of several tens of microseconds.

Parameters:: microSecond – [in] The timeout interval (in microseconds) for which execution is paused. Up to (2^32-1) microseconds can be specified.

WMX3APIFUNC PrintToServerConsole(const char *format, ...)

Print a message to the Console Screen.

This function signals the engine to print a formatted string to the Rtx Server Console. The Rtx Server Console is a component of the RTX operating system that displays messages to the user in Windows space.

Remark

Parameters:: format – [in] The char string to print. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

WMX3APIFUNC PrintToServerConsole(const wchar_t *format, ...)

Print a message to the Console Screen.

This function is a variation of PrintToServerConsole that accepts a wchar_t string for the formatted string. Use this function whne using Unicode character sets.

Remark

Parameters:: format – [in] The wchar_t string to print. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

WMX3APIFUNC RecordWindowsUpdates(unsigned int waitTimeMilliseconds = 0)

Record a list of installed Windows Updates to file.

This function records to file a list of Windows Updates that are currently installed to the system.

Remark

This function can be used in conjunction with the CompareWindowsUpdates function to detect changes to the Windows Updates that are installed to the system.

The file that is created by this function is stored in the C:\ProgramData\SoftServo\WMX3 directory with the file name InstalledWindowsUpdates.dat.

This function will overwrite the existing file if there is any.

This function can execute without a device (this function can be called before calling CreateDevice).

Parameters:: waitTimeMilliseconds – [in] An optional parameter that is used to specify the maximum amount of time that this function can block before returning. If this parameter is not specified, there is no limit to the amount of time that this function can block.

WMX3APIFUNC CompareWindowsUpdates(unsigned int waitTimeMilliseconds = 0)

Compare the list of currently installed Windows Updates to the list recorded to file.

This function compares the file generated by the RecordWindowsUpdates function against the Windows Updates that are currently installed to the system.

Remark

This function returns the UpdatesListUninitialized error code if the file is not found.

This function returns the UpdatesListDoesNotMatchInstalledUpdates error code if the file is found, but its contents do not match the Windows Updates that are currently installed to the system. This can occur if a new Windows Update has been installed or an existing Windows Update has been uninstalled since the time that the RecordWindowsUpdates function was last called.

This function can execute without a device (this function can be called before calling CreateDevice).

One way to use this function is as follows:

Call this function immediately before calling CreateDevice. Calling this function will not start the real time operating system.
If this function returns the UpdatesListDoesNotMatchInstalledUpdates error, display a warning message to the user.
If the user confirms that the installed Windows Updates are compatible with the real time operating system, call CreateDevice as usual to start the WMX3 engine.
After the WMX3 engine starts, RecordWindowsUpdates should be called to update the file containing the list of installed Windows Updates. This way, the warning message will be displayed again only if there is another change in the installed Windows Updates.

Parameters:: waitTimeMilliseconds – [in] An optional parameter that is used to specify the maximum amount of time that this function can block before returning. If this parameter is not specified, there is no limit to the amount of time that this function can block.

Public Members

HANDLE dev: Reserved.

Public Static Functions

static WMX3APIFUNC ErrorToString(int errCode, char *pString, unsigned int size)

Get a string representation of the specified error code.

This function returns a string representation of the specified error code. The error code must be defined in the ErrorCode enum. All errors returned by functions in class WMX3Api will be defined in this enum. Errors returned by functions in other classes may not be defined in this enum, and when such errors are passed to this function, an ErrorCodeNotDefined error will be returned and pString will contain the string representation of this error.

Remark

If pString is too small to contain the entire string representation of the error code, pString will be set to an empty string. An array size of 256 characters will be enough to hold all string representations.

This function is static, and may be called without declaring an instance of the WMX3Api class or creating a device.

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A char array that will contain the string representation of the error.
size – [in] The size of the char array in number of characters.

static WMX3APIFUNC ErrorToString(int errCode, wchar_t *pString, unsigned int size)

Get a string representation of the specified error code.

This function is a variation of ErrorToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A wchar_t array that will contain the string representation of the error.
size – [in] The size of the wchar_t array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, char *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function converts the raw data for one API function call that was extracted from the API log with the GetApiLogData function.

Remark

See also

Extracting the API Log Information

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the pLogData char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A char array that will contain the string representation of the raw data of the API log.
size – [in] The size of the pString char array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, wchar_t *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function is a variation of ApiLogToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A wchar_t array that will contain the string representation of the raw data of the API log.
size – [out] The size of the pString wchar_t array in number of characters.

static WMX3APIFUNC GetLibVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module library.

This function is static, and may be called without declaring an instance of this class or creating a device.

Remark

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.

static WMX3APIFUNC GetIMDllVersion(int *pVersion, int *pRevision)

Get the version of the IMDll.

This function is static, and may be called without declaring an instance of this class or creating a device.

Remark

Parameters:

pVersion – [out] The version number.
pRevision – [out] The revision number.

static WMX3APIFUNC PrintToFile(const char *filePath, const char *format, ...)

Append a string to a file.

This function appends a formatted string to a file. If the file does not exist, a new file is created.

Remark

The char string after formatting must be 1024 characters or less. If the char string after formatting exceeds 1024 characters, the BufferTooSmall error is returned.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A char array that contains the file path of the file to append to as a null-terminated string.
format – [in] The char string to append. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

static WMX3APIFUNC PrintToFile(const wchar_t *filePath, const wchar_t *format, ...)

Append a string to a file.

This function is a variation of PrintToFile that accepts a wchar_t string. Use this function when using Unicode character sets.

Remark

The wchar_t string after formatting must be 1024 characters or less. If the wchar_t string after formatting exceeds 1024 characters, the BufferTooSmall error is returned.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A wchar_t array that contains the file path of the file to append to as a null-terminated string.
format – [in] The wchar_t string to append. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

static WMX3APIFUNC PrintToFile(const char *filePath, int charsToPrint, const char *buff)

Append a string to a file.

This function appends a string to file. If the file does not exist, a new file is created.

Remark

Characters are printed to file until charsToPrint characters are printed or the end of the string (the null terminator) is reached, whichever comes first.

There is no limit to the number of characters that can be printed with each function call. However, format specifiers cannot be specified.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A char array that contains the file path of the file to append to as a null-terminated string.
charsToPrint – [in] The number of characters to print from the string specified to buff.
buff – [in] The null-terminated char string to print to file.

static WMX3APIFUNC PrintToFile(const wchar_t *filePath, int charsToPrint, const wchar_t *buff)

Append a string to a file.

This function is a variation of PrintToFile(const char* filePath, int charsToPrint, const char* buff) that accepts a wchar_t string. Use this function when using Unicode character sets.

Remark

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A wchar_t array that contains the file path of the file to append to as a null-terminated string.
charsToPrint – [in] The number of wchar_t characters to print from the string specified to buff.
buff – [in] The null-terminated wchar_t string to print to file.

static WMX3APIFUNC PrintToFileIfExist(const char *filePath, const char *format, ...)

Append a string to a file.

This function appends a formatted string to a file. If the file does not exist, an error is returned.

Remark

The char string after formatting must be 1024 characters or less. If the char string after formatting exceeds 1024 characters, the BufferTooSmall error is returned.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A char array that contains the file path of the file to append to as a null-terminated string.
format – [in] The char string to append. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

static WMX3APIFUNC PrintToFileIfExist(const wchar_t *filePath, const wchar_t *format, ...)

Append a string to a file.

This function is a variation of PrintToFileIfExist that accepts a wchar_t string. Use this function whne using Unicode character sets.

Remark

The wchar_t string after formatting must be 1024 characters or less. If the wchar_t string after formatting exceeds 1024 characters, the BufferTooSmall error is returned.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A wchar_t array that contains the file path of the file to append to as a null-terminated string.
format – [in] The wchar_t string to append. This argument can contain format specifiers followed by additional arguments in the same manner as the C/C++ printf() function.

static WMX3APIFUNC PrintToFileIfExist(const char *filePath, int charsToPrint, const char *buff)

Append a string to a file.

This function appends a string to file. If the file does not exist, an error is returned.

Remark

Characters are printed to file until charsToPrint characters are printed or the end of the string (the null terminator) is reached, whichever comes first.

There is no limit to the number of characters that can be printed with each function call. However, format specifiers cannot be specified.

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A char array that contains the file path of the file to append to as a null-terminated string.
charsToPrint – [in] The number of characters to print from the string specified to buff.
buff – [in] The null-terminated char string to print to file.

static WMX3APIFUNC PrintToFileIfExist(const wchar_t *filePath, int charsToPrint, const wchar_t *buff)

Append a string to a file.

This function is a variation of PrintToFileIfExist(const char* filePath, int charsToPrint, const char* buff) that accepts a wchar_t string. Use this function whne using Unicode character sets.

Remark

This function is static, and may be called without declaring an instance of this class or creating a device.

Parameters:

filePath – [in] A wchar_t array that contains the file path of the file to append to as a null-terminated string.
charsToPrint – [in] The number of wchar_t characters to print from the string specified to buff.
buff – [in] The null-terminated wchar_t string to print to file.

static WMX3APIFUNC GetStdOutStr(char *buff, int buffSize, unsigned char *isWideChar, int *strlen)

Get the character string stored in the WMX3 engine message output buffer.

This function gets the string stored in the WMX3 engine message output buffer. By setting “2” to the StdOut key in Module.ini, the WMX3 engine message will be output to the message output buffer. If a value other than “2” is set in the StdOut key of Module.ini, or if the StdOut key is not set, the WMX3 engine message cannot be acquired with this function. (For details, see the description of Module.ini in GeneralHelp.)

Remark

When a string is obtained from the message output buffer using this function, the obtained string is deleted from the message output buffer. If the size of the specified output buffer is smaller than the size of the string stored in the message output buffer, the substring that can fit in the specified output buffer size is obtained.

If this function is used, resources are reserved in the WMX3 engine, and it is necessary to release the resources by calling the ReleaseStdOut function before the program ends.

Parameters:

buff – [out] A buffer that outputs the character string stored in the message output buffer.
buffSize – [in] The size of the buffer that outputs the character string stored in the message output buffer.
isWideChar – [out] If 1, wide characters are stored in message output buffer. If 0, multibyte characters are stored in the message output buffer.
strlen – [out] Number of characters in the string that was obtained from the message output buffer.

static WMX3APIFUNC GetStdOutDataSize()

Get the size of the string stored in the WMX3 engine message output buffer.

This function gets the size of the string stored in the WMX3 engine message output buffer. If this function is used, resources are reserved in the WMX3 engine, and it is necessary to release the resources by calling the ReleaseStdOut function before the program ends.

Remark

static WMX3APIFUNC ClearStdOut()

Clear the string stored in the WMX3 engine message output buffer.

This function clears the string stored in the WMX3 engine message output buffer. If this function is used, resources are reserved in the WMX3 engine, and it is necessary to release the resources by calling the ReleaseStdOut function before the program ends.

Remark

static WMX3APIFUNC ReleaseStdOut()

Release resources related to the WMX3 engine message output buffer.

This function releases resources opened by the WMX3 engine when any of the following functions is called.

Remark

GetStdOutStr
GetStdOutDataSize
ClearStdOut

If any of the above functions is called, this function must be called before the program ends to release resources.