1C:Enterprise script extension

To become an extension of 1C:Enterprise script, the add-in must implement the ILanguageExtender interface. This interface inherits IUnknown. It is intended for extending 1C:Enterprise script. To use this extension, call the New operator and pass the string having the AddIn.<ExtensionName> format to it, where <ExtensionName> is returned by a method of this interface. Then you can call the properties and methods of the created object.

Version 2.0 supports creation of several AddIn.<ExtensionName> objects. However, in this case the add-in must specify that version 2.0 is supported in the GetInfo() method. Otherwise you will be able to create a single object only.

RegisterExtensionAs

Description:

Stores the extension name to the pExtensionName variable. The add-in object allocates memory for storing the string using the standard system functions that work with COM strings (for example, SysAllocString()). 1C:Enterprise will release this memory by calling SysFreeString().

Syntax:

HRESULT RegisterExtensionAs(BSTR* pExtensionName);

Parameters:

pExtensionName

Type: BSTR*. 1C:Enterprise script extension name.

Return value:

• S_OK

GetNProps

Description:

Returns the number of extension properties, or 0 if there are no properties available. 1C:Enterprise allocates memory for the plProps variable.

Syntax:

HRESULT GetNProps(long* plProps);

Parameters:

plProps

Type: long*. Pointer to the variable that contains the number of extension properties.

Return value:

• S_OK

FindProp

Description:

Returns the sequential number of the property with name pszPropName, or -1 if the property is not found. 1C:Enterprise allocates memory for the plPropNum variable.

The first property has sequential number 0.

Syntax:

HRESULT FindProp(BSTR pszPropName, long* plPropNum);

Parameters:

pszPropName

Type: BSTR. Property name.

plPropNum

Type: long*. Pointer to the variable that will store the sequential property number.

Return value:

• S_OK - operation completed successfully.

• S_FALSE - the property with name pszPropName is not available in the extension.

GetPropName

Description:

Writes the name of the property with sequential number lPropNum to the pPropName variable. If there is no property with the specified sequential number, writes an empty string to this variable. The add-in object allocates memory for storing the string using the standard system functions that work with COM strings (for example, SysAllocString()). 1C:Enterprise will release this memory by calling SysFreeString().

Syntax:

HRESULT GetPropName(long lPropNum, long lAliasNum, BSTR* pPropName);

Parameters:

lPropNum

Type: long. Sequential number of the property.

lAliasNum

Type: long. Language of the property name:

• 0 - English name.

• 1 - local name.

pPropName

Type: BSTR*. Pointer to the string that will contain the property name.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no property with the specified sequential number.

GetPropVal

Description:

Writes the value of the property with sequential number lPropNum to the pvPropVal variable. If there is no property with the specified sequential number or the property is unavailable for reading, the variable will have the VT_EMPTY type.

Syntax:

HRESULT GetPropVal(long lPropNum, VARIANT* pvPropVal);

Parameters:

lPropNum

Type: long. Sequential number of the property.

pvPropVal

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

Return value:

• S_OK - successful completion.

• S_FALSE - there is no property with the specified sequential number, or the property is not available for reading.

SetPropVal

Description:

Stores the value of the property with sequential number lPropNum to the pvPropVal variable.

Syntax:

HRESULT SetPropVal(long lPropNum, VARIANT* pvPropVal);

Parameters:

lPropNum

Type: long. Sequential number of the property.

pvPropVal

Type: VARIANT*. The VARIANT structure that stores the new property value.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no property with the specified sequential number, or the property is not available for writing, or the value passed to pvPropVal cannot be converted to the required type.

IsPropReadable

Description:

Stores the flag that shows whether the property with sequential number lPropNum is readable to the pboolPropReadable variable. FALSE (0) - the property is not available for reading, TRUE (1) - the property is available for reading. If there is no property with this number, the method returns S_FALSE.

Syntax:

HRESULT IsPropReadable(long lPropNum, BOOL* pboolPropReadable);

Parameters:

lPropNum

Type: long. Sequential number of the property.

pboolPropReadable

Type: BOOL*. Pointer to the variable that contains the flag that shows whether the property is readable.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no property with the specified sequential number.

IsPropWritable

Description:

Stores the flag that shows whether the property with sequential number lPropNum is writable to the pboolPropWritable variable. FALSE (0) - the property is not available for writing, TRUE (1) - the property is available for writing. If there is no property with this number, the method returns S_FALSE.

The first method has sequential number 0. The first method parameter has sequential number 0.

Syntax:

HRESULT IsPropWritable(long lPropNum, BOOL* pboolPropWritable);

Parameters:

lPropNum

Type: long. Sequential number of the property.

pboolPropWritable

Type: BOOL*. Pointer to the variable that contains the flag that shows whether the property is writable.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no property with the specified sequential number.

GetNMethods

Description:

Stores the number of methods in the extension to the plMethods variable (or 0 if there are no methods available).

Syntax:

HRESULT GetNMethods(long* plMethods);

Parameters:

plMethods

Type: long*. Pointer to the variable that will contain the number of methods in the extension.

Return value:

• S_OK

FindMethod

Description:

Stores the sequential number of the method with the bstrMethodName name to the plMethNum variable (or -1 if there is no method with the specified number).

Syntax:

HRESULT FindMethod(BSTR bstrMethodName, long* plMethNum);

Parameters:

bstrMethodName

Type: BSTR. Method name.

plMethNum

Type: long*. Pointer to the value that contains the sequential number of the method with name bstrMethodName.

Return value:

• S_OK

GetMethodName

Description:

Stores the name of the method with the specified sequential number to the pbstrMethName variable. If there is no method with the specified sequential number, writes an empty string to this variable. The add-in object allocates memory for storing the string using the standard system functions that work with COM strings (for example, SysAllocString()). 1C:Enterprise will release this memory by calling SysFreeString().

Syntax:

HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR* pbstrMethName);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

lAliasNum

Type: long. Language of the method name:

• 0 - English name.

• 1 - local name.

pbstrMethName

Type: BSTR*. Pointer to the string that will contain the method name.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no method with the specified sequential number.

GetNParams

Description:

Writes the number of parameters of the method with sequential number lMethodNum to the plMethParams variable. If there is no method with the specified sequential number or the method has no parameters, writes 0 to this variable. 1C:Enterprise allocates memory for storing the variable.

The first method parameter has sequential number 0.

Syntax:

HRESULT GetNParams(long lMethodNum, long* plMethParams);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

plMethParams

Type: long*. Pointer to the variable that will contain the number of method parameters.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no method with the specified sequential number.

GetParamDefValue

Description:

Writes the default value of the parameter with sequential number lParamNum of the method with sequential number lMethodNum to the pvParamDefVal 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 VT_EMPTY type. 1C:Enterprise allocates memory for storing the variable.

The first method has sequential number 0. The first method parameter has sequential number 0.

Syntax:

HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT* pvParamDefVal);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

lParamNum

Type: long. Sequential number of the parameter.

pvParamDefVal

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

Return value:

• S_OK - successful completion (even if the parameter does not have a default value).

• S_FALSE - there is no method or parameter with the specified sequential number.

HasRetVal

Description:

Writes the flag that indicates whether the method with sequential number lMethodNum has a return value to the pboolHasRetVal variable: TRUE if the method has a return value and FALSE if it does not have a return value. 1C:Enterprise allocates memory for storing the variable.

The first method has sequential number 0.

Syntax:

HRESULT HasRetVal(long lMethodNum, BOOL* pboolHasRetVal);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

pboolHasRetVal

Type: BOOL*. Pointer to the variable that will contain the flag that indicates whether the method has a return value.

Return value:

• S_OK - successful completion.

• S_FALSE - there is no method with the specified sequential number.

CallAsProc

Description:

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

The first method has sequential number 0.

Syntax:

HRESULT CallAsProc(long lMethodNum, SAFEARRAY** pVars);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

pVars

Type: SAFEARRAY**. Double pointer to the VARIANT array of structures that contains method parameter values. If the method has no parameters, the array must contain NULL.

Return value:

• S_OK - successful completion, no errors occurred.

• E_FAIL - the method was called and a runtime error occurred. The module execution is interrupted.

• S_FALSE - there is no method with the specified sequential number.

CallAsFunc

Description:

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

The first method has sequential number 0.

Syntax:

HRESULT CallAsFunc(long lMethodNum, VARIANT* pRetValue, SAFEARRAY** pVars);

Parameters:

lMethodNum

Type: long. Sequential number of the method.

pRetValue

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

pVars

Type: SAFEARRAY**. Double pointer to the VARIANT array of structures that contains method parameter values. If the method has no parameters, the array must contain NULL.

Return value:

• S_OK - successful completion, no errors occurred.

• E_FAIL - the method was called and a runtime error occurred. The module execution is interrupted.

• S_FALSE - there is no method with the specified sequential number.