Add-in interface

This section describes interfaces that the add-in can implement.

Init

Description:

During 1C:Enterprise startup, it initializes the add-in object by running the Init() method and passing the pointer to IAddInDefBase to this method. The object can save the pointer for further use.

Syntax:

bool Init(void* Interface);

Parameters:

Interface

Type: void*. Pointer to 1C:Enterprise interface.

Return value:

  • true - successful completion.
  • false - errors occurred.

setMemManager

Description:

Sets a memory manager for the add-in. When a return value of an add-in method cannot be fully transferred through the stack, the add-in must allocate the memory using the AllocMemory() function provided by the memory manager. 1C:Enterprise will release this memory later using the FreeMemory() function.

Warning. Memory allocation for return values using new or malloc() is not allowed because it will lead to memory leaks and unstable software operation.

Syntax:

bool setMemManager(void* memManager);

Parameters:

memManager

Type: void*. Pointer to 1C:Enterprise memory manager interface.

Return value:

  • true - successful completion.
  • false - errors occurred.

GetInfo

Description:

1C:Enterprise calls this method to get add-in details. Example: version 3.56 is represented as the number 3560.

Syntax:

long GetInfo();

Return value:

The add-in version.

Done

Description:

1C:Enterprise calls this method when it finishes working with the add-in object. This method is called regardless of the object initialization result (the Init() method).

Syntax:

void Done();

Return value:

None.

RegisterExtensionAs

Description:

Registers a 1C:Enterprise script extension. The extension name is passed to the wsExtName parameter. The add-in object allocates memory for storing this string using the AllocMemory() function of the memory manager. 1C:Enterprise releases that memory by calling FreeMemory().

Syntax:

bool RegisterExtensionAs(WCHAR_T** wsExtName);

Parameters:

wsExtName

Type: WCHAR_T**. Name of the 1C:Enterprise script extension.

Return value:

  • true - successful completion.
  • false - errors occurred.

GetNProps

Description:

Returns the number of extension properties.

Syntax:

long GetNProps();

Return value:

  • long - number of extension properties, or 0 if there are no properties available.

FindProp

Description:

Returns the sequential number of the property by property name. The first property has a sequential number 0.

Syntax:

long FindProp(const WCHAR_T* wsPropName);

Parameters:

wsPropName

Type: const WCHAR_T*. Property name.

Return value:

  • a sequential number of the property.
  • -1 - if the property is not found.

GetPropName

Description:

Returns the name of the property with sequential number lPropNum. If there is no property with the specified sequential number, returns NULL. The add-in object allocates memory for storing this string using the AllocMemory() function of the memory manager. 1C:Enterprise releases that memory by calling FreeMemory().

Syntax:

const WCHAR_T* GetPropName(long lPropNum, long lPropAlias);

Parameters:

lPropNum

Type: long. The sequential number of the property.

lPropAlias

Type: long. Language of the property name:

  • 0 - English name.
  • 1 - local name.

Return value:

  • Property name.
  • NULL - there is no property with the specified sequential number.

GetPropVal

Description:

Stores the value of the property with a sequential number lPropNum to the pvarPropVal variable. If there is no property with the specified sequential number or the property is unavailable for reading, the variable will have the VTYPE_EMPTY type. If the value has string type, the add-in allocates memory for storing this string using the AllocMemory() function. 1C:Enterprise will release that memory.

Syntax:

bool GetPropVal(const long lPropNum, tVariant* pvarPropVal);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

pvarPropVal

Type: tVariant*. Pointer to the tVariant structure that will store the property value.

Return value:

  • true - successful completion.
  • false - errors occurred.

SetPropVal

Description:

The pvarPropVal variable stores the value for the property with sequential number lPropNum. If there is no property with the specified number, the property is unavailable for writing, or the value passed to pvarPropVal has an incorrect type, the method returns false.

Syntax:

bool SetPropVal(const long lPropNum, tVariant* pvarPropVal);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

pvarPropVal

Type: tVariant*. The tVariant structure containing the new property value.

Return value:

  • true - successful completion.
  • false - errors occurred.

IsPropReadable

Description:

Returns the flag that shows whether the property with sequential number lPropNum is readable. If there is no property with this number, the method returns false.

Syntax:

bool IsPropReadable(const long lPropNum);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

Return value:

  • true - reading is available.
  • false - reading is unavailable.

IsPropWritable

Description:

Returns the flag that shows whether the property with sequential number lPropNum is writable. If there is no property with this number, the method returns false.

Syntax:

bool IsPropWritable(const long lPropNum);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

Return value:

  • true - writing is available.
  • false - writing is unavailable.

GetNMethods

Description:

Returns the number of methods in the extension.

Syntax:

long GetNMethods();

Return value:

  • a number of methods in the extension.
  • 0 - there are no methods.

The first method has a sequential number 0.

FindMethod

Description:

Returns the sequential number of the method with the wsMethodName name.

Syntax:

long FindMethod(const WCHAR_T* wsMethodName);

Parameters:

wsMethodName

Type: const WCHAR_T*. Method name.

Return value:

  • a sequential number of the method.
  • -1 - there is no method with the specified number.

The first method has a sequential number 0.

GetMethodName

Description:

Returns the name of the method with the specified sequential number. If there is no method with this number, the method returns NULL. The add-in object allocates memory for storing this string using the AllocMemory() function of the memory manager. 1C:Enterprise releases that memory by calling FreeMemory().

Syntax:

const WCHAR_T* GetMethodName(const long lMethodNum, const long lMethodAlias);

Parameters:

lMethodNum

Type: const long. The sequential number of the method.

lMethodAlias

Type: const long. Language of the method name:

  • 0 - English name.
  • 1 - local name.

Return value:

  • Method name.
  • NULL - there is no method with the specified sequential number.

GetNParams

Description:

Returns the number of parameters of the method with sequential number lMethodNum.

Syntax:

long GetNParams(const long lMethodNum);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

Return value:

  • a number of method parameters.
  • 0 - there is no method with the specified number, or the method has no parameters.

The first method has a sequential number 0.

GetParamDefValue

Description:

Writes the default value of the parameter with sequential number lParamNum of the method with sequential number lMethodNum to the pvarParamDefVal variable. If there is no method with the specified number, no parameter with the specified number, or the parameter has no default value, the variable will have the VTYPE_EMPTY type. If the default value has VTYPE_PSTR, VTYPE_PWSTR, or VTYPE_BLOB type, the add-in allocates memory for storing this string using the AllocMemory() function of the memory manager, writes data to that memory, and saves the address in the corresponding structure field. 1C:Enterprise releases that memory by calling FreeMemory().

Syntax:

bool GetParamDefValue(const long lMethodNum, const long lParamNum, tVariant* pvarParamDefValue);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

lParamNum

Type: const long. Sequential number of the parameter.

pvarParamDefValue

Type: tVariant*. Pointer to the tVariant structure that will contain the default parameter value.

Return value:

  • true - successful completion (even if the parameter does not have a default value).
  • false - errors occurred.

HasRetVal

Description:

Returns the flag that indicates whether the method with sequential number lMethodNum has a return value.

Syntax:

bool HasRetVal(const long lMethodNum);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

Return value:

  • true - the method returns a value.
  • false - the method has no return value.

CallAsProc

Description:

Executes the method with sequential number lMethodNum. If the method returns false, a runtime error occurs and 1C:Enterprise module execution is interrupted. 1C:Enterprise allocates memory for the array of parameters and releases it later.

Syntax:

bool CallAsProc(const long lMethodNum, tVariant* paParams, const long lSizeArray);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

paParams

Type: tVariant*. Pointer to the tVariant array of structures that contains method parameter values. If the method has no parameters, the array must contain NULL.

lSizeArray

Type: const long. Size of the paParams array.

Return value:

  • true - the method was called, no errors occurred.
  • false - the method is not found or a runtime error occurred.

CallAsFunc

Description:

Executes the method with sequential number lMethodNum. If the method returns false, a runtime error occurs and 1C:Enterprise module execution is interrupted. 1C:Enterprise allocates memory for the array of parameters. If the return value has string or binary data type, the add-in allocates memory using the AllocMemory() function of the memory manager, writes data to that memory, and saves the address in the corresponding structure field. 1C:Enterprise releases that memory by calling FreeMemory().

Syntax:

bool CallAsFunc(const long lMethodNum, tVariant* pvarRetValue, tVariant* paParams, const long lSizeArray);

Parameters:

lMethodNum

Type: const long. The sequential number of the method.

pvarRetValue

Type: tVariant*. Pointer to the tVariant structure that will contain the return value.

paParams

Type: tVariant*. Pointer to the tVariant array of structures that contains method parameter values. If the method has no parameters, the array must contain NULL.

lSizeArray

Type: const long. Size of the paParams array.

Return value:

  • true - the method was called, no errors occurred.

  • false - the method is not found or a runtime error occurred.

Next page: Localization

Be the first to know tips & tricks on business application development!

A confirmation e-mail has been sent to the e-mail address you provided .

Click the link in the e-mail to confirm and activate the subscription.