How to make an Axxium plug-in
Knowledge base article
Goal of this document is to be a reference manual for developing an Axxium Plug-In.
Contents
Contents ............................................................................................................. 1
Heading 1 .................................................................... Error! Bookmark not defined.
Heading 2 ............................................................................. Error! Bookmark not defined.
Heading 3 .......................................................................... Error! Bookmark not defined.
Axxium Plug-In Wrapper functions
This chapter describes the Axxium Plug-In “wrapper” functions.
Wrapper functions are declared as extern “C” functions. Each one of these functions must have
the extended attribute declaration __declspec() (Microsoft specific) with the dllexport storage
class attribute.
This chapter will often refer to the example on page ……. This example adds the functionality of the
Left function to Axxium. The class in which this function is implemented calls the
CTextManipulation class.
Create
Syntax: void* CreateObjectFunctionName (void)
Goal
This function typically creates an instance of your class
Called
The first time the function is used in one call
Returns
This function must return a pointer to your object
Arguments
No arguments
Example
void *CreateObjectLeft(void)
Mandatory
Yes
Delete
Syntax: void DeleteObjectFunctionName (void* pcObject)
1
9.02.16
How to make an Axxium plug-in
Goal
This function typically destructs the instance of your class, created by the
CreateObject function
Called
At the end of the call
Returns
Nothing
Example
void DeleteObjectLeft(void *pcObject)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
Mandatory
Yes
Init
Syntax: void InitObjectFunctionName (void* pcObject)
Goal
This function typically initializes the member variables of the object, created by
the CreateObject function.
Called
Each time before calling the set of setter functions
Returns
Nothing
Example
void InitObjectLeft(void *pcObject)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
Mandatory
No
Uninit
Syntax: void UninitObjectFunctionName (void* pcObject)
Goal
This function typically reinitializes the member variables of the object after
execution.
Called
Each time time after calling the set of getter functions
Returns
Nothing
Example
void UninitObjectLeft(void *pcObject)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
Mandatory
No
2
9.02.16
How to make an Axxium plug-in
Set functions
Syntax: void SetParamFunctionName_ParameterName (void* pcObject,
char* szParameter)
Goal
These functions fill the object member variables with a value received from the
Axxium project
Called
Before function execution
Returns
Nothing
Example
void SetParameterLeft_SourceText(void *pcObject, char* szSourceText)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
char* szParameterValue : Pointer to a character array holding the value that
must be copied to your object member variable
Mandatory
No
Remark
One “Set function” can be called more than once from within the application
Get functions
Syntax: void GetParamFunctionName_ParameterName (void* pcObject, char*
szParameter)
Goal
These functions asks for the value of one of your object member variables
Called
After function execution
Returns
Nothing
Example
void GetParameterLeft_ModifiedText(void *pcObject, char* szModifiedText)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
char* szParameterValue : Pointer to a character array where the value of your
object member variable must be copied to
Mandatory
No
Remark
The maximum size of the character array szParameter is 4096 bytes.
If you need to send more bytes towards your Axxium project, you
must use the GetParamEx function.
3
9.02.16
How to make an Axxium plug-in
Extended Get functions
Syntax: void GetParamExFunctionName_ParameterName (void* pcObject, char*
szParameter, int* nSize)
Goal
These functions ask for the value of one of your object member variables. The
default size that is send towards your Plug-In is 4096. If this is enough, you
just have to copy the value of your member variable to the szParameter
argument. In case you need to copy more bytes, you have to change the value
of nSize with the number of characters you need to copy. The Axxium runtime
will allocate the necessary number of bytes and will recall this function with the
requested size. This time your function can copy the value of your member
variable to the memory, indicated by the character pointer szParameter.
Called
After function execution
Returns
Nothing
Example
void GetParameterLeft_ModifiedText(void *pcObject, char* szModifiedText)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
char* szParameterValue : Pointer to a character array where the value of your
object member variable must be copied to
Mandatory
No
Execute functions
Syntax: void FunctionName (void* pcObject)
Goal
This function should call the execute function of your object
Called
Between setting and getting the parameters from your Axxium application
Returns
Nothing
Example
void Left (void *pcObject)
Arguments
void* pcObject : The pointer to your object that was returned by the
CreateObject function
Mandatory
Yes
Example
Best way to explain how an Axxium Plug in works is with an example. The example we will add the
Left function to your Axxium project.
4
9.02.16
How to make an Axxium plug-in
Left function
The Left function returns a specified number of characters from the left side of a string.
Example: Left of the string “Hello world” (3 characters) = “Hel”.
In our example, one is not compelled to specify the length. The default value is 1. So Left of the
string “Hello world” without specifying the length will result in the string “H”.
Internal left class
This section describes the class containing the Left function.
class CTextManipulation
{
public :
CTextManipulation(void);
// Constructor
virtual ~CTextManipulation(); // Destructor
void
void
void
void
void
Init(void);
SetSourceText(const char* szSourceText);
SetLength(const char* szLength);
GetModifiedText(char* szModifiedText);
Left(void);
private :
char m_szSourceText[SOURCETEXT_SIZE];
char m_szModifiedText[MODIFIEDTEXT_SIZE];
int m_nLength;
};
Wrapper function
This section lists the wrapper functions that are used in the Left example.
#include <windows.h>
extern "C"
{
__declspec(dllexport) void* CreateObjectLeft(void)
{
// Return the pointer of a newly created object
return ((void *) new CTextManipulation);
}
__declspec(dllexport) void DeleteObjectLeft(void* pcTextManipulation)
{
5
9.02.16
How to make an Axxium plug-in
delete (CTextManipulation *)pcTextManipulation;
}
__declspec(dllexport) void InitObjectLeft(void* pcTextManipulation)
{
((CTextManipulation *)pcTextManipulation)->Init();
}
__declspec(dllexport) void SetParamLeft_SourceText(
void* pcTextManipulation,
char* szText)
{
((CTextManipulation *)pcTextManipulation)->SetSourceText(szText);
}
__declspec(dllexport) void SetParamLeft_Length(
void* pcTextManipulation,
char* szLength)
{
((CTextManipulation *)pcTextManipulation)->SetLength(szLength);
}
__declspec(dllexport) void Left(void* pcTextManipulation)
{
((CTextManipulation *)pcTextManipulation)->Left();
}
__declspec(dllexport) void GetParamLeft_ModifiedText(
void* pcTextManipulation,
char* szText)
{
((CTextManipulation*)pcTextManipulation)->
GetModifiedText(szText);
}
}
Implementation of class functions
This section tersely describes what has to be done for the implementation of the different class
functions.
Init
This function should initialize the member variables, in particular the members that are set by your
Axxium project.
SetSourceText
This function should copy the argument to the local class member m_szSourceText. You can use
the standard function strcpy for this.
6
9.02.16
How to make an Axxium plug-in
SetLength
The argument of this function is a char*. The purpose is to copy the value in this argument to the
local member variable m_nLength, which is an integer. A conversion should be performed here.
Use the standard atoi function for this conversion.
Left
This function will use the class members m_szSourceText and m_nLength in order to fill the
member m_szModifiedText. You can use the standard function strncpy to copy m_nLength
characters from m_szSourceText to m_szModifiedText (Don’t forget to set the terminating zero).
GetModifiedText
This function should copy the result (value of the member m_szModifiedText) to the memory,
indicated by the pointer char* szModifiedText which is the argument of this function.
Function calls in Axxium
The picture below shows you the sequence of the function calls.
7
9.02.16
How to make an Axxium plug-in
CTextManipulation*
CreateObjectLeft
CTextManipulation*
InitObjectLeft
CTextManipulation*
char* SourceText
SetParamLeft_SourceText
CTextManipulation*
char* Length
SetParamLeft_Length
CTextManipulation*
Left
CTextManipulation*
char * ModifiedText
GetParamLeft_ModifiedText
CTextManipulation*
InitObjectLeft
CTextManipulation*
char* SourceText
SetParamLeft_SourceText
CTextManipulation*
Left
CTextManipulation*
char * ModifiedText
GetParamLeft_ModifiedText
CTextManipulation*
DeleteObjectLeft
Remark
Notice that in the second X-Icon state, the parameter Length is NOT
set. In this case, the value assigned to the member variable
m_nLenght by the InitObjectLeft function, will be considered.
Suppose the Init function was not implemented. What should happen
in this case?
Answer: The value of the member m_nLength will keep the value of
the previous X-Icon execution (= value 5).
8
9.02.16
How to make an Axxium plug-in