Creating add-ins with COM technology

Content

Creating add-ins with COM technology

This technology is not suitable for development of Windows Runtime, Android, and iOS applications.

When loading an add-in developed using COM technology with the LoadAddIn() or AttachAddIn(<Location>,<Name>, <Type>) function, 1C:Enterprise defines ProgID of the COM object as follows:

  • ProgID has the following format: Vendor.AddIn.

  • The "AddIn" string is used as the first part (Vendor).

  • The string with ID 100 from the add-in strings table is used as the second part (AddIn). The string can have the following format: Name1|Name2|...|NameN; in this case all objects with ProgID matching the AddIn.NameX format will be created. If there is no such string, the add-in file name is used, without the file extension.

If you use the AttachAddIn(<ObjectID>) function, pass the ProgID of the add-in COM object as the function parameter. It can be a string of the following format: ProgID1|ProgID2|...|ProgIDX.

Initializing and unloading add-ins

Use the IInitDone interface for initializing and unloading the add-in. The interface inherits from IUnknown. It is intended for initializing objects and finishing working with them.

Init

Description:

During 1C:Enterprise startup, it initializes the add-in object by running the Init() method and passing the pointer to IDispatch to this method. The object can save the pointer for further use. The object can get all other 1C:Enterprise interfaces by calling the QueryInterface() method of the IDispatch interface passed to it. The object returns S_OK on successful initialization or E_FAIL if an error occurred. The method can use the IErrorLog interface for displaying error info. The initialization is considered unsuccessful if any of the passed EXCEPINFO structures has the scode field value not equal to S_OK. All data passed to IErrorLog and then returned is processed when the method execution is complete. When the method is called, the AppDispatch property is not defined.

Syntax:

HRESULT Init(IDispatch* pBackConnection);

Parameters:

pBackConnection

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

Return value:

  • E_FAIL - errors occurred.

  • S_OK - successful initialization.

Done

Description:

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

Syntax:

HRESULT Done(void);

Return value:

  • S_OK - the object operation is complete.

GetInfo

Description:

1C:Enterprise calls this method to get add-in details. In add-in creation technology version 2.0, write the supported technology version to the element with index 0 in the V_I4 format. It is an integer with a major version number represented as thousands, and a minor version number represented as units. For example, version 1.0 should be passed as 1000. All add-in objects can support version 1.0 (number 1000) or version 2.0 (number 2000). 1C:Enterprise allocates memory for pInfo. The method must return S_OK.

The add-in object must implement this interface. If the interface is not available, the add-in cannot be loaded.

Syntax:

HRESULT GetInfo(SAFEARRAY** pInfo);

Parameters:

pInfo

Type: SAFEARRAY**. Double pointer to the VARIANT structures array. 1C:Enterprise will allocate memory for the array.

Return value:

  • S_OK - add-in details are returned.

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.

Localization

SetLocale

Description:

1C:Enterprise calls this method to set add-in locale by locale code. The add-in can configure its environment to ensure correct data presentation.

Syntax:

HRESULT SetLocale(BSTR bstrLocale);

Parameters:

bstrLocale

Type: BSTR. Locale string in the following format: <language>-<REGION>. Example: en-US.

Return value:

  • S_OK

Using COM VARIANT type in data exchange

Calling add-in functions

1C:Enterprise and COM type mapping:

  • Values of VT_EMPTY type are mapped to Undefined values.

  • Values of VT_I4 type are mapped to integer values, they are stored in lVal.

  • Values of VT_R8 type are mapped to noninteger values, they are stored in dblVal. Note that the precision of the internal presentation can exceed the precision of a double value (about 15 decimal digits), therefore conversion can lead to a loss of precision.

  • Values of VT_DATE type are mapped to date values, they are stored in date.

  • Values of VT_BSTR type are mapped to string values, they are stored in bstrVal.

  • Values of VT_DISPATCH type are mapped to object values, they are stored in pdispVal. To use a 1C:Enterprise object from the add-in, define the DISPIDs of the object methods in the add-in by calling the GetIDsOfNames() method, and then call Invoke().

When a COM object is converted to IDispatch, a check for cyclic calls 1C:Enterprise -> add-in -> 1C:Enterprise and add-in -> 1C:Enterprise -> add-in is performed to ensure correct interaction between the add-in and 1C:Enterprise.

Returning values from add-ins

1C:Enterprise and COM type mapping:

  • Values of VT_EMPTY type are mapped to Undefined values. When such a value is passed as a method parameter, the default parameter value is used.

  • Values of VT_I2, VT_I4, VT_BOOL, VT_ERROR, and VT_UI1 types are mapped to integer values, they are stored in lVal.

  • Values of VT_R4, VT_R8, and VT_CY types are mapped to noninteger values, they are stored in dblVal.

  • Values of VT_DATE type are mapped to date values, they are stored in date.

  • Values of VTYPE_BSTR type are mapped to string values, they are stored in bstrVal.

  • Values of VT_ARRAY type are mapped to array values, they are stored in parray.

  • Values of VT_DISPATCH type are mapped to object values, they are stored in pdispVal.

    Warning! VT_DECIMAL, VT_VARIANT, and VT_UNKNOWN types are not supported.

    When a COM object is converted to IDispatch, a check for cyclic calls 1C:Enterprise -> add-in -> 1C:Enterprise and add-in -> 1C:Enterprise -> add-in is performed to ensure correct interaction between the add-in and 1C:Enterprise.

    Calling 1C:Enterprise object methods from add-ins

    To call an object method, call the Invoke() method of the IDispatch interface (which is received earlier), and pass all required parameters to this method, including the DISPID of the object method being called. You can get the DISPIDs by calling the GetIDsOfNames() method of the IDispatch interface and passing the method name to it.
    The object method parameters have a direct correspondence with the VARIANT array of structures: the structure with index 0 corresponds to the first parameter, the structure with index 1 corresponds to the second parameter, and so on. Note that when you pass object method parameters, you have to pass all parameter values, including those having default values. To include all default values automatically, assign the VT_ERROR type to the corresponding VARIANT structure.

    COM interfaces of 1C:Enterprise

    You can get all interfaces listed in this document by calling the QueryInterface() method of the pointer to IDispatch object passed during the initialization. Their identifiers (IIDs) are included in the templates delivered with this document.

    Saving add-in object parameters

    To save parameters, an add-in object can utilize 1C:Enterprise data saving algorithms by using the IPropertyProfile interface. This interface inherits from the IPropertyBag interface (a standard COM interface), with a single method difference:

    RegisterProfileAs

    Description:

    Registers the list of add-in parameters with name bstrProfileName.

    When saving or loading parameters, you can represent them as a tree. For that purpose, in the Read() and Write() methods, provide parameter names in the following format: Node1\Node2\...\NodeN\ParameterName:DefaultParameterValue. The parameters are stored in the profile that corresponds to the current computer - infobase - user combination.

    Syntax:

    HRESULT RegisterProfileAs(BSTR bstrProfileName);

    Parameters:

    bstrProfileName

    Type: BSTR. Name of the list of add-in parameters.

    Return value:

    • S_OK - successful registration.

    • E_FAIL - an error occurred during registration. The error message is displayed in the message window.

    Notification messages about object states

    An object can use the IErrorLog interface for generating user notifications. It is a standard COM interface, the description of the AddError() method is provided here only for convenience. New notifications are processed at run time (if they are queued asynchronously), on returning from the Init() method, and on returning from add-in methods. All messages are queued and processed in the order they were added. The number of stored messages is not limited.

    AddError

    Description:

    Adds a notification message from a 1C:Enterprise script extension method.

    Possible message codes:

    #define ADDIN_E_NONE              1000

    #define ADDIN_E_ORDINARY          1001

    #define ADDIN_E_ATTENTION         1002

    #define ADDIN_E_IMPORTANT         1003

    #define ADDIN_E_VERY_IMPORTANT    1004

    #define ADDIN_E_INFO              1005

    #define ADDIN_E_FAIL              1006

    #define ADDIN_E_MSGBOX_ATTENTION  1007

    #define ADDIN_E_MSGBOX_INFO       1008

    #define ADDIN_E_MSGBOX_FAIL       1009

    The message code is stored to the wCode field of the EXEPINFO structure. Error codes in range 1000 - 2000 are reserved.

    During the notification processing, warning dialog boxes are displayed for notifications with the following codes: ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO, and ADDIN_E_MSGBOX_FAIL. For the rest of the codes, notifications are displayed in the message window. Notification descriptions have the following format:

    <Icon> <ErrorSource> : <ErrorDescription> (Error code = <ErrorCode>)

    The following icons are available:

    • ADDIN_E_NONE. No icon

    • ADDIN_E_ORDINARY. ">" icon

    • ADDIN_E_ATTENTION. "!" icon

    • ADDIN_E_IMPORTANT. "!!" icon

    • ADDIN_E_VERY_IMPORTANT. "!!!" icon

    • ADDIN_E_INFO. "i" icon

    • ADDIN_E_FAIL. "!!!" icon

    If an icon code is not found in the list, no icon is displayed.

    ErrorSource - the bstrSource field in the EXCEPINFO structure.

    ErrorDescription - the bstrDescription field in the EXCEPINFO structure.

    ErrorCode - numeric message code in a decimal form. The message code is not displayed if one of the codes listed above is used.

    For notifications with codes ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO, or ADDIN_E_MSGBOX_FAIL, a dialog box is displayed, which contains the OK button and the icon MB_ICONEXCLAMATION, MB_ICONINFORMATION, or MB_ICONERROR respectively.

    Notification descriptions have the following format:

    <ErrorSource>:<ErrorDescription> (Error code = <ErrorCode>)

    where ErrorSource, ErrorDescription, and ErrorCode are described above.

    Syntax:

    HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo);

    Parameters:

    pszPropName

    Type: BSTR. In this implementation, the pszPropName parameter is ignored.

    pExcepInfo

    Type: LPEXCEPINFO. Pointer to the EXCEPINFO structure.

    Return value:

    • S_OK - the message is successfully added.

    • E_OUTOFMEMORY - not enough memory.

    • Other return codes that inform about errors are possible.

    Dialog boxes

    To provide user interaction, an object can use the standard COM interface IMsgBox, which is inherited from IUnknown. The interface is not available on the server or in external connections.

    Confirm

    Description:

    Displays a dialog box with text specified in queryText and buttons OK and Cancel.

    Syntax:

    HRESULT Confirm(const BSTR queryText, VARIANT* retVal);

    Parameters:

    queryText

    Type: BSTR. Question text.

    retVal

    Type: VARIANT. Return value of the dialog box, which has VT_BOOL type: TRUE for clicking OK, or FALSE for clicking Cancel.

    Return value:

    • S_OK - the dialog box is displayed.

    • E_FAIL - displaying dialog boxes is not supported.

    Alert

    Description:

    Displays a simple notification dialog box with text specified in queryText and OK button.

    Syntax:

    HRESULT Alert(BSTR queryText);

    Parameters:

    queryText

    Type: BSTR. Message text.

    Return value:

    • S_OK - the dialog box is displayed.

    • E_FAIL - displaying dialog boxes is not supported.

    Getting platform info

    To get information about the application that attached the add-in, you can use the standard COM interface IPlatformInfo, which is inherited from IUnknown.

    GetPlatformInfo

    Description:

    Requests platform info. If the add-in is attached to 1C:Enterprise version earlier than 8.3.3 using a web client, only the Application field of the AppInfo structure is filled.

    Syntax:

    HRESULT GetPlatformInfo(AppInfo** info)

    Parameters:

    info

    Type: AppInfo**- pointer to a structure with the following fields:

    • AppVersion. Type: BSTR, application version.

    • Application. Type: enumeration, type of application that attached the add-in.

    • UserAgentInformation. Type: BSTR, browser info (for the web client only).

    Return value:

    • S_OK - successful completion.

    External events

    When an asynchronous event is fired (for example, barcode reading), an object can use the IAsyncEvent interface for creating an external event in 1C:Enterprise. The IAsyncEvent interface inherits from IUnknown. All events are queued and processed in the order they are added. The number of stored events is limited to the queue size. During the initialization, the queue size is set to 1 and then it can be changed by calling the SetEventBufferDepth() method and retrieved using the GetEventBufferDepth() method. A separate queue is maintained for each add-in object. External event processing is performed using the predefined ExternEventProcessing() procedure and external event handlers in form modules.

    SetEventBufferDepth

    Description:

    Sets the event queue size for an object. If the number of events in the queue exceeds the queue size, the latest events are deleted.

    Syntax:

    HRESULT SetEventBufferDepth(long lDepth);

    Parameters:

    lDepth

    Type: long. The event queue size.

    Return value:

    • S_OK - the event queue size is successfully set.

    • E_FAIL - an error occurred while setting the event queue size.

    • Other return codes that inform about errors are possible.

    GetEventBufferDepth

    Description:

    Stores the event queue size of the specified object to the plDepth variable.

    Syntax:

    HRESULT GetEventBufferDepth(long* plDepth);

    Parameters:

    plDepth

    Type: long*. Pointer to the variable that will contain the event queue size.

    Return value:

    • S_OK -the event queue size is successfully obtained.

    • E_FAIL - an error occurred while getting the event queue size.

    • Other return codes that inform about errors are possible.

    ExternalEvent

    Description:

    Adds an event to the queue, storing the event source, name, and parameters. During event processing, that data is passed to the ExternEventProcessing() procedure. Once the ExternalEvent() method is called, the event processing is performed as follows:

      1. The event is stored to the event queue (if the queue is full, the event is lost).

      2. If no system events are available and the queue is not empty, the first event is taken from the queue.

      3. External event processing is started.

        This procedure is repeated for all add-in objects, so that external event processing is synchronized with system event processing.

        Syntax:

        HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData);

        Parameters:

        bstrWho

        Type: BSTR. A string that contains the event source.

        bstrWhat

        Type: BSTR. A string that contains the event name.

        bstrData

        Type: BSTR. A string that contains the event parameters.

        Return value:

        • S_OK - the event is added to the queue.

        • E_FAIL - the queue is full, or unknown error.

        • E_OUTOFMEMORY - not enough memory.

        • Other return codes that inform about errors are possible.

        CleanBuffer

        Description:

        Clears the event queue by deleting all events from the queue.

        Syntax:

        HRESULT CleanBuffer();

        Return value:

        • S_OK - the queue is cleared.

        • E_FAIL - an error occurred while clearing the queue.

        • Other return codes that inform about errors are possible.

        Status bar operations

        The add-in object can use the IStatusLine interface to inform the user about its status. The SetStatusLine() method displays a text in the status bar. The ResetStatusLine() method clears the status bar.

        SetStatusLine

        Description:

        Sets status bar text.

        Syntax:

        HRESULT SetStatusLine(BSTR bstrStatusText);

        Parameters:

        bstrStatusText

        Type: BSTR. Status bar text.

        Return value:

        • S_OK - the text is displayed in the status bar.

        • E_FAIL - unknown error.

        • Other return codes that inform about errors are possible.

        ResetStatusLine

        Description:

        Clears the status bar.

        Syntax:

        HRESULT ResetStatusLine();

        Return value:

        • S_OK - the status bar is cleared.

        • E_FAIL - unknown error.

        • Other return codes that inform about errors are possible.

        Creating windows in 1C:Enterprise environment

        Add-ins can create windows (dialog boxes) for displaying data using the IExtWndsSupport interface. Add-ins can create both modal and nonmodal dialog boxes.

        Modal dialog boxes

        Modal dialog boxes are created by the add-in itself. A modal dialog box requires specifying the parent window returned by the GetAppMainFrame() method (otherwise the operating system will treat the dialog box as a standalone task with its own taskbar button). 1C:Enterprise functioning is paused until the dialog box is closed.

        Nonmodal dialog boxes

        Nonmodal dialog boxes are also created by the add-in itself. A nonmodal dialog box requires specifying the parent window returned by the GetAppMDIFrame() method (otherwise the operating system will treat the dialog box as a standalone task with its own taskbar button). The dialog box does not pause 1C:Enterprise functioning and is similar to 1C:Enterprise forms. However, the dialog box is not added to the list of open 1C:Enterprise windows or to the open items panel, and therefore we do not recommend using such dialog boxes (use 1C:Enterprise forms instead).

        In 1C:Enterprise, dialog box creation is supported with some limitations for compatibility with existing add-ins. We recommend that you use forms with ActiveX or ActiveDocument controls for displaying custom data in 1C:Enterprise windows. The IExtWndsSupport interface methods are listed below.

        Warning! The web client does not support opening windows.

        GetAppMainFrame

        Description:

        Returns the descriptor of the main 1C:Enterprise window.

        Syntax:

        HRESULT GetAppMainFrame(HWND* pHWnd);

        Parameters:

        pHWnd

        Type: HWND*. Pointer to the window descriptor.

        Return value:

        • S_OK

        GetAppMDIFrame

        Description:

        Returns the descriptor of the active 1C:Enterprise window.

        Syntax:

        HRESULT GetAppMDIFrame(HWND* pHWnd);

        Parameters:

        pHWnd

        Type: HWND*. Pointer to the window descriptor.

        Return value:

        • S_OK

        Accessing 1C:Enterprise methods and properties using OLE automation

        The functionality described in this section is only available in the add-in creation technology version 2.0.

        A pointer to the IDispatch interface passed to the Init() method provides access to 1C:Enterprise using OLE Automation. You can get the read-only AppDispatch property from that pointer. This property contains the pointer to 1C:Enterprise's IDispatch (which is different from the one passed to Init()). While the add-in is connecting to the web client, the AppDispatch property is not yet available.

        The AppDispatch property becomes available only after the full initialization of the 1C:Enterprise platform, therefore at the moment of loading the add-in and calling Init() this property provides access to a limited set of 1C:Enterprise functions.

        Accessing 1C:Enterprise interface methods and properties using OLE automation

        Visual Basic interface support is limited. The most "natural" mechanism for Visual Basic is working with OLE Automation. The Object type that represents a pointer to IDispatch is used for this purpose in Visual Basic. Therefore, 1C:Enterprise provides the option to use OLE Automation by passing the pointer to IDispatch in the Init() method and supporting calls of the interface methods listed above through OLE Automation.

        Methods and properties available through OLE Automation

        Methods available in the add-in creation technology version 1.0:

        • RegisterProfileAs(<ParameterListName>)

        • Read(<VariableName>,<ReferenceToVARIANT>)

        • Write(<VariableName>,<ReferenceToVARIANT>) 

        • SetEventBufferDepth(<EventQueueLength>)

        • GetEventBufferDepth(<ReferenceToQueueLength>)

        • ClearEventBuffer()

        • ExternalEvent(<EventSourceString>,<EventNameString>,<EventParametersString>)

        • AddError(<MessageCode>,<MessageSourceString>,<MessageDescriptionString>,<ErrorCode>)

        • SetStatusLine(<StatusBar>)

        • ResetStatusLine()

        Methods and properties added in the add-in creation technology version 2.0:

        Warning! Methods and properties listed below are unavailable in the web client.

        • AppDispatch property

        • GetAppMainFrame(<PointerToWindowDescriptor>)

        • GetAppMDIFrame(<PointerToWindowDescriptor>)

        Specifics of add-in development using COM

        Add-ins developed using the COM technology do not have to be initially installed on the end-user computer. The AttachAddIn(<Location>,<Name>,<Type>) method gets the add-in file from the infobase (provided that the file is stored in the infobase) and calls the DllInstall function, which registers add-in objects. If the registration at the user side is unsuccessful, the DllRegisterServer function is called. If the user does not have enough access rights, add-in registration and attachment are not allowed. Developers must provide a possibility to register the add-in from a user account with their current rights. If the add-in has its own installer, the installation process must include the add-in registration for all of the computer users.