290 lines
24 KiB
C
290 lines
24 KiB
C
///
|
|
/// Copyright (c) Aerotech, Inc.
|
|
///
|
|
|
|
#ifndef AUTOMATION1TASK_H_INCLUDED
|
|
#define AUTOMATION1TASK_H_INCLUDED
|
|
|
|
#if defined(_MSC_VER)
|
|
#if defined(AUTOMATION1_CAPI_EXPORT)
|
|
#define AUTOMATION1_CAPI __declspec(dllexport)
|
|
#else
|
|
#define AUTOMATION1_CAPI __declspec(dllimport)
|
|
#endif
|
|
#elif defined(__GNUC__)
|
|
#define AUTOMATION1_CAPI __attribute__((visibility ("default")))
|
|
#endif
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
#include "Automation1Controller.h"
|
|
#include "Automation1Enum.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/// @brief Represents the status of a controller task on an Automation1 controller.
|
|
typedef struct Automation1TaskStatus
|
|
{
|
|
/// @brief The task index corresponding to this status.
|
|
int32_t TaskIndex;
|
|
/// @brief The error on the task, if any. This will be zero if there is no error.
|
|
int32_t Error;
|
|
/// @brief The human readable error message corresponding to the error on the task, if any.
|
|
/// This string will be empty if there is no error on the task.
|
|
char ErrorMessage[2048];
|
|
/// @brief The warning on the task, if any. This will be zero if there is no warning.
|
|
int32_t Warning;
|
|
/// @brief The human readable warning message corresponding to the warning on the task, if any.
|
|
/// This string will be empty if there is no warning on the task.
|
|
char WarningMessage[2048];
|
|
/// @brief The state of execution for the task.
|
|
Automation1TaskState TaskState;
|
|
/// @brief The value of the task mode on the task.
|
|
Automation1TaskMode TaskMode;
|
|
/// @brief The null-terminated name of the compiled AeroScript file for the program that is loaded or running on the task.
|
|
/// This string will be empty if no program is loaded.
|
|
char AeroScriptSourceFileName[1024];
|
|
/// @brief The null-terminated name of the compiled AeroScript file for the program that is loaded or running on the task.
|
|
/// The name will be empty if no program is loaded.
|
|
char CompiledAeroScriptFileName[1024];
|
|
} Automation1TaskStatus;
|
|
|
|
/// @brief A handle that represents the arguments provided to a callback by an AeroScript program.
|
|
/// This handle will be the first argument provided to your callback function.
|
|
/// Use the Automation1_Task_CallbackGetArguments() function to get the values of each argument using this handle.
|
|
typedef struct Automation1TaskCallbackArguments_T* Automation1TaskCallbackArguments;
|
|
|
|
/// @brief A handle that represents the values or error message that will be returned from a callback to an AeroScript program.
|
|
/// This handle will be the second argument provided to your callback function.
|
|
/// Use the Automation1_Task_CallbackSetReturn() function to set the return values if the callback was successful.
|
|
/// Use the Automation1_Task_CallbackSetErrorMessage() function to set the error message if the callback was unsuccessful.
|
|
typedef struct Automation1TaskCallbackReturn_T* Automation1TaskCallbackReturn;
|
|
|
|
/// @brief A function type that represents a callback that can be raised from an AeroScript program.
|
|
/// You must return true from this function type if the callback was successful, or return false if the callback was unsuccessful.
|
|
/// Use the Automation1_Task_CallbackRegister() function to register an Automation1TaskCallback function so that it can be raised from an AeroScript program.
|
|
/// You can only register a callback ID once per task. To change the registration of a callback ID, unregister it first. To do that see Automation1_Task_CallbackUnregister().
|
|
/// Use the Automation1_Task_CallbackGetArguments() function to get the arguments from the Automation1TaskCallbackArguments handle.
|
|
/// Use the Automation1_Task_CallbackSetReturn() function to set the return values of the Automation1TaskCallbackReturn handle.
|
|
/// Use the Automation1_Task_CallbackSetErrorMessage() function to set the error message of the Automation1TaskCallbackReturn handle.
|
|
typedef bool(*Automation1TaskCallback)(Automation1TaskCallbackArguments, Automation1TaskCallbackReturn);
|
|
|
|
/// @brief Gets the current status of one or more tasks.
|
|
/// @param[In] controller The controller to get the array of task status from.
|
|
/// @param[Out] taskStatusArrayOut The out array of task status that was obtained from the controller.
|
|
/// The size of this array determines which tasks to obtain status for. For example, if this array has a size of 3, the status for task 0, task 1,
|
|
/// and task 2 are obtained from the controller and populated into the taskStatusArrayOut argument in that order.
|
|
/// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function.
|
|
/// @param[In] taskStatusArrayLength The maximum number of elements to copy to the taskStatusArrayOut argument.
|
|
/// This must not be greater than the length of the taskStatusArrayOut array.
|
|
/// @return Returns true if the task status was successfully obtained otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_GetStatus(Automation1Controller controller, Automation1TaskStatus* taskStatusArrayOut, int32_t taskStatusArrayLength);
|
|
|
|
/// @brief Runs the specified controller file as an AeroScript program on this task. If the controller file is an AeroScript source file then the file will first be compiled.
|
|
/// Running a program will automatically load the program and begin program execution on this task. This function waits for the program to load and start but it does not
|
|
/// wait for the program to complete.
|
|
/// The AeroScript program must exist as a controller file on the Automation1 controller.
|
|
/// AeroScript libraries cannot be run on a task, the controller file must be an AeroScript program (either a source program file or a compiled program file).
|
|
/// @param[In] controller The controller to run the program on.
|
|
/// @param[In] taskIndex The task to run the program on.
|
|
/// @param[In] controllerFileName The null-terminated name of the controller file that is the AeroScript program to run on this task (source program file or compiled program file).
|
|
/// @return Returns true if the program was successfully started on the specified task otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_ProgramRun(Automation1Controller controller, int32_t taskIndex, const char* controllerFileName);
|
|
|
|
/// @brief Loads the specified controller file as an AeroScript program on this task. If the controller file is an AeroScript source file then the file will first be compiled.
|
|
/// Loading does not start the program, you must call Automation1_Task_ProgramStart() to begin program execution on this task.
|
|
/// The AeroScript program must exist as a controller file on the Automation1 controller.
|
|
/// AeroScript libraries cannot be loaded on a task, the controller file must be an AeroScript program (either a source program file or a compiled program file).
|
|
/// @param[In] controller The controller to load the program onto.
|
|
/// @param[In] taskIndex The task to load the program onto.
|
|
/// @param[In] controllerFileName The null-terminated name of the controller file that is the AeroScript program to load on this task (source program file or compiled program file).
|
|
/// @return Returns true if the program was successfully loaded onto the specified task otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_ProgramLoad(Automation1Controller controller, int32_t taskIndex, const char* controllerFileName);
|
|
|
|
/// @brief Starts or resumes the currently loaded AeroScript program on this task, beginning program execution. A program must be loaded on to
|
|
/// this task to be able to start or resume it. To load a program, call Automation1_Task_ProgramLoad. This function waits for the loaded program
|
|
/// to start but it does not wait for the program to complete.
|
|
/// @param[In] controller The controller to start or resume the program on.
|
|
/// @param[In] taskIndex The task to start or resume the program on.
|
|
/// @return Returns true if the program successfully started or resumed otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_ProgramStart(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Stops the currently running AeroScript program on this task, terminating program execution.
|
|
/// This function will wait for the specified amount of time for the loaded program to stop. If the timeout is set to -1, this function will wait indefinitely.
|
|
/// After a program is stopped it is unloaded from the task. This function will also end a command queue running on this task.
|
|
/// @param[In] controller The controller to stop the program on.
|
|
/// @param[In] taskIndex The task to stop the program on.
|
|
/// @param[In] millisecondsTimeout The number of milliseconds to wait to stop the program on this task.
|
|
/// If the program takes longer than this amount of time to stop, the function will fail.
|
|
/// This function will wait indefinitely for the loaded program to stop if this value is set to - 1.
|
|
/// @return Returns true if the program stopped successfully before the specified amount of time otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_ProgramStop(Automation1Controller controller, int32_t taskIndex, int32_t millisecondsTimeout);
|
|
|
|
/// @brief Pauses the currently running AeroScript program on this task, suspending program execution.
|
|
/// This function will wait for the specified amount of time for the loaded program to pause. If the timeout is set to -1, this function will wait indefinitely.
|
|
/// To resume program execution, call Automation1_Task_ProgramStart().
|
|
/// @param[In] controller The controller to pause the program on.
|
|
/// @param[In] taskIndex The task to pause the program on.
|
|
/// @param[In] millisecondsTimeout The number of milliseconds to wait to pause the program on this task.
|
|
/// If the program takes longer than this amount of time to stop, the function will fail.
|
|
/// This function will wait indefinitely for the loaded program to stop if this value is set to - 1.
|
|
/// @return Returns true if the program paused successfully before the specified amount of time otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_ProgramPause(Automation1Controller controller, int32_t taskIndex, int32_t millisecondsTimeout);
|
|
|
|
/// @brief Performs a single line of program execution on the currently paused AeroScript program on this task, stepping into any function calls.
|
|
/// This function can only be called if there is an AeroScript program loaded on this task and it is paused.
|
|
/// @param[In] controller The controller to execute the single line of program execution on.
|
|
/// @param[In] taskIndex The task to execute the single line of program execution on.
|
|
/// @return Returns true if the single line of program execution executed successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_DebugStepInto(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Performs a single line of program execution on the currently paused AeroScript program on this task, stepping over any function calls.
|
|
/// This function can only be called if there is an AeroScript program loaded on this task and it is paused.
|
|
/// @param[In] controller The controller to execute the single line of program execution on.
|
|
/// @param[In] taskIndex The task to execute the single line of program execution on.
|
|
/// @return Returns true if the single line of program execution executed successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_DebugStepOver(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Performs execution on the currently paused AeroScript program on this task, stepping out of the current function call.
|
|
/// This function can only be called if there is an AeroScript program loaded on this task and it is paused.
|
|
/// @param[In] controller The controller to execute the single line of program execution on.
|
|
/// @param[In] taskIndex The task to execute the single line of program execution on.
|
|
/// @return Returns true if the single line of program execution executed successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_DebugStepOut(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Enables retrace mode for the running AeroScript program on the specified task.
|
|
/// When you enable retrace mode, the controller executes motion and motion-synchronized functions in reverse order, through functions
|
|
/// that were previously executed. The controller keeps a history of moves and synchronized commands that it can use for retrace.
|
|
/// @param[In] controller The controller on which to enable retrace.
|
|
/// @param[In] taskIndex The task on which to enable retrace.
|
|
/// @return Returns true if retrace was successfully enabled, otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_RetraceOn(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Disables retrace mode for the running AeroScript program on the specified task.
|
|
/// When you disable retrace mode, the controller executes forward through the retrace history until it moves to the program line
|
|
/// where retrace was activated.
|
|
/// @param[In] controller The controller on which to disable retrace.
|
|
/// @param[In] taskIndex The task on which to disable retrace.
|
|
/// @return Returns true if retrace was successfully disabled, otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_RetraceOff(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Enables the feedhold state on the specified task.
|
|
/// Enabling the feedhold state causes motion on the task to immediately decelerate and it stops the execution of programs
|
|
/// and immediate commands on the task.
|
|
/// @param[In] controller The controller on which to enable feedhold.
|
|
/// @param[In] taskIndex The task on which to enable feedhold.
|
|
/// @return Returns true if the feedhold state was successfully enabled, otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_FeedholdOn(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Disables the feedhold state on the specified task.
|
|
/// Disabling the feedhold state causes motion on the task to accelerate back up to the speed it was before feedhold was enabled.
|
|
/// Also, the execution of programs and immediate commands on the task continues once the feedhold state is disabled.
|
|
/// @param[In] controller The controller on which to disable feedhold.
|
|
/// @param[In] taskIndex The task on which to disable feedhold.
|
|
/// @return Returns true if the feedhold state was successfully disabled, otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_FeedholdOff(Automation1Controller controller, int32_t taskIndex);
|
|
|
|
/// @brief Sets the MFO (manual feedrate override) for the specified task.
|
|
/// This scales the programmed feedrate for all coordinated motion and the motion generated by the MoveRapid() AeroScript function.
|
|
/// The MFO percentage multiplied by the programmed feedrate determines the true feedrate of the move. To get the current value
|
|
/// of MFO for this task, use Status (see Automation1_Status_GetTaskResult()) to retrieve Automation1TaskStatusItem_Mfo.
|
|
/// @param[In] controller The controller on which to set MFO.
|
|
/// @param[In] taskIndex The task on which to set MFO.
|
|
/// @param[In] mfoPercent The MFO percentage to set.
|
|
/// @return Returns true if MFO was set successfully, otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_SetMfo(Automation1Controller controller, int32_t taskIndex, double mfoPercent);
|
|
|
|
/// @brief Registers a callback that can be raised by an AeroScript program.
|
|
/// You must return true from the handler if the callback was successful, or return false if the callback was unsuccessful.
|
|
/// You can only register a callback ID once per task. To change the registration of a callback ID, unregister it first. To do that see Automation1_Task_CallbackUnregister().
|
|
/// @param[In] controller The controller to register a callback on.
|
|
/// @param[In] taskIndex The task to register a callback on.
|
|
/// @param[In] callbackId A number that uniquely identifies the callback per task.
|
|
/// @param[In] handler The code to execute when the callback is raised by an AeroScript program on this task.
|
|
/// @return Returns true if the callback was registered successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_CallbackRegister(Automation1Controller controller, int32_t taskIndex, int32_t callbackId, Automation1TaskCallback handler);
|
|
|
|
/// @brief Unregisters a callback on a task.
|
|
/// @param[In] controller The controller to unregister a callback on.
|
|
/// @param[In] taskIndex The task to unregister a callback on.
|
|
/// @param[In] callbackId A number that uniquely identifies the callback per task.
|
|
/// @return Returns true if the callback was unregistered successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_CallbackUnregister(Automation1Controller controller, int32_t taskIndex, int32_t callbackId);
|
|
|
|
/// @brief Gets the arguments provided to a callback by an AeroScript program.
|
|
/// @param[In] callbackArguments The callback arguments handle that is provided to a callback function.
|
|
/// @param[Out] taskIndexOut The task that this callback was raised on.
|
|
/// @param[Out] callbackIdOut The unique identifier of this callback on the task that it was raised on.
|
|
/// @param[Out] aeroScriptIntegersOut The array of integer values provided to the callback by an AeroScript program.
|
|
/// @param[Out] aeroScriptIntegersLengthOut The length of the aeroScriptIntegersOut array.
|
|
/// This argument will be set to the exact length if the aeroScriptIntegersOut argument is null.
|
|
/// If the aeroScriptIntegersOut argument is not null, this will be set to the number of integers that was actually copied into aeroScriptIntegersOut.
|
|
/// To avoid calling this function twice to get the exact size, set this parameter based on number of integers you would typically provide to your callback.
|
|
/// @param[Out] aeroScriptRealsOut The array of real values provided to the callback by an AeroScript program.
|
|
/// @param[Out] aeroScriptRealsLengthOut The length of the aeroScriptRealsOut array.
|
|
/// This argument will be set to the exact length if the aeroScriptRealsOut argument is null.
|
|
/// If the aeroScriptRealsOut argument is not null, this will be set to the number of reals that was actually copied into aeroScriptRealsOut.
|
|
/// To avoid calling this function twice to get the exact size, set this parameter based on number of reals you would typically provide to your callback.
|
|
/// @param[Out] aeroScriptStringsOut The array of string values provided to the callback by an AeroScript program.
|
|
/// AeroScript strings will be null-terminated and stored in succession based on the maxAeroScriptStringLengthOut argument.
|
|
/// The number of strings that will be copied is based on the aeroScriptStringsLengthOut argument.
|
|
/// The length of each string in aeroScriptStringsOut is based on the maxAeroScriptStringLengthOut argument.
|
|
/// Thus, the number of bytes that will be copied into this array is the product of the aeroScriptStringsLengthOut and maxAeroScriptStringLengthOut arguments.
|
|
/// Set this argument to null to get the exact values for the aeroScriptStringLengthsOut and maxAeroScriptStringLengthOut arguments.
|
|
/// @param[Out] aeroScriptStringsLengthOut The length of the aeroScriptStringsOut array.
|
|
/// This argument will be set to the exact length if the aeroScriptStringsOut argument is null.
|
|
/// If the aeroScriptStringsOut argument is not null, this will be set to the number of strings that was actually copied into aeroScriptStringsOut.
|
|
/// To avoid calling this function twice to get the exact size, set this parameter based on number of strings you would typically provide to your callback.
|
|
/// @param[Out] maxAeroScriptStringLengthOut The maximum length of each AeroScript string (including the null-terminator).
|
|
/// This argument will be set to the exact length if the aeroScriptStringsOut argument is null.
|
|
/// If aeroScriptStringsOut is not null, this will be set to the actual max string length that was used to copy strings into aeroScriptStringsOut.
|
|
/// To avoid calling this function twice to get the exact size, set this parameter to 1000 characters.
|
|
/// @return Returns true if all arguments were copied successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_CallbackGetArguments(Automation1TaskCallbackArguments callbackArguments, int32_t* taskIndexOut, int32_t* callbackIdOut, int64_t* aeroScriptIntegersOut, int32_t* aeroScriptIntegersLengthOut, double* aeroScriptRealsOut, int32_t* aeroScriptRealsLengthOut, char* aeroScriptStringsOut, int32_t* aeroScriptStringsLengthOut, int32_t* maxAeroScriptStringLengthOut);
|
|
|
|
/// @brief Sets the values to return to an AeroScript program when this callback succeeds.
|
|
/// These values will only be returned to an AeroScript program if the callback that sets these values returns true.
|
|
/// @param[In] callbackReturn The callback return handle that is provided to a callback function.
|
|
/// @param[In] aeroScriptIntegers The array of integers to return to an AeroScript program.
|
|
/// @param[In] aeroScriptIntegersLength The length of the aeroScriptIntegers array.
|
|
/// @param[In] aeroScriptReals The array of reals to return to an AeroScript program.
|
|
/// @param[In] aeroScriptRealsLength The length of the aeroScriptReals array.
|
|
/// @param[In] aeroScriptStrings The array of null-terminated strings to return to an AeroScript program.
|
|
/// @param[In] aeroScriptStringsLength The length of the aeroScriptStrings array.
|
|
/// @return Returns true if the return values were set successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_CallbackSetReturn(Automation1TaskCallbackReturn callbackReturn, int64_t* aeroScriptIntegers, int32_t aeroScriptIntegersLength, double* aeroScriptReals, int32_t aeroScriptRealsLength, const char** aeroScriptStrings, int32_t aeroScriptStringsLength);
|
|
|
|
/// @brief Sets the error message to return to an AeroScript program when this callback fails.
|
|
/// This error message will only be returned to an AeroScript program if the callback that sets the error message returns false.
|
|
/// @param[In] callbackReturn The callback return handle that is provided to a callback function.
|
|
/// @param[In] errorMessage The null-terminated string that will be displayed in the error message of an AeroScript program.
|
|
/// @return Returns true if the error message was set successfully otherwise returns false.
|
|
/// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information.
|
|
AUTOMATION1_CAPI bool Automation1_Task_CallbackSetErrorMessage(Automation1TaskCallbackReturn callbackReturn, const char* errorMessage);
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif // AUTOMATION1TASK_H_INCLUDED
|