1C:Enterprise 8.3 platform
13/01/2022

Add-in creation technology

Overview

The main goal of 1C:Enterprise is solving various issues related to automation of company activities. With its powerful tools and official features, you can set up the application to meet specific data processing needs of a certain company. At the same time, 1C:Enterprise is an open system. You can interact with external applications by using tools of data import/export in text and XML formats. The system also supports the OLE Automation application integration standard and supports access via web services. However, some special integration tasks might require closer interaction between 1C:Enterprise and other applications.

For this particular reason, we developed the Add-in technology. You can use it to create applications that will be dynamically attached and will closely interact with 1C:Enterprise extending its features. With add-ins, you can perform a wide range of specific tasks including those related to using point-of-sale equipment and 1C:Enterprise together. Add-ins can be attached to both 1C:Enterprise server and client applications including the web client.

The distribution package contains this guide and a set of add-in implementation examples using different technologies.

In the guide, you will learn how to create add-ins using Native API and COM.

Structure of "Add-in technology" distribution package directories

The include directory contains a set of included header files for add-in creation.

The lib directory contains static libraries used to build extensions for Mozilla Firefox, Google Chrome, Safari, and Internet Explorer.

The example directory contains examples of add-ins developed using COM and Native API. In the directory, you can also find examples of extensions for browsers and mobile platforms.

The template directory contains a template you can use to create add-ins using Native API.

The templateMobile directory contains a template that will help you to create add-ins for the mobile platform using Native API.

Creating add-ins using Native API

With Native API technology, you can create add-ins that can be attached both in a client application and on 1C:Enterprise server in versions for Microsoft Windows, Linux, Microsoft Windows Runtime, Android, and iOS.

For Microsoft Windows Runtime, Android, and iOS, the user interface is unavailable.

An add-in implements one or several of its objects that can be used in 1C:Enterprise. Each add-in object must be inherited from the abstract IComponentBase class (ComponentBase.h file is part of the distribution package) and implement all of its methods.

The add-in developed under this technology must export the following functions from the library:

GetClassNames

Syntax:

Copy to clipboard
const WCHAR_T* GetClassNames()

Return value:

const WCHAR_T*

Description:

Gets a list of add-in object names.

GetClassObject

Syntax:

Copy to clipboard
long GetClassObject(const WCHAR_T* clsName, IComponentBase** pIntf)

Parameters:

Return value:

Description:

Creates an add-in object instance. Returns 0 if the object cannot be created or the object with specified name is not found.

DestroyObject

Syntax:

Copy to clipboard
long DestroyObject(IComponentBase** pIntf)

Parameters:

Return value:

Description:

Deletes an instance of an earlier created object. The add-in must delete the object and free the memory used by it using internal tools. Returns 0 upon successful completion. Otherwise, returns the runtime error code.

SetPlatformCapabilities

Syntax:

Copy to clipboard
AppCapabilities SetPlatformCapabilities(const AppCapabilities capabilities)

Parameters:

Description:

Sets the version of features supported by the platform. The add-in must return the version that it can operate with. If the function is not implemented, the add-in cannot display messages and request information about the platform.

GetAttachType

Syntax:

Copy to clipboard
AttachType GetAttachType()

Parameters:

Description:

The add-in must return a supported attachment type that it can operate with. If the function is not implemented, the add-in will be attached depending on the configuration compatibility mode.

Possible values:

 

Add-in interface

Init

Syntax:

Copy to clipboard
bool Init(void* Interface)

Parameters:

Return value:

Description:

Upon import, 1C:Enterprise initializes the add-in object by calling the Init method and passing a pointer to IAddInDefBase. The object can save this pointer to use it later. The object returns True if the initialization is successfully completed and False if an error occurred.

setMemManager

Syntax:

Copy to clipboard
bool setMemManager(void* memManager)

Parameters:

Return value:

Description:

Installs a memory manager for an add-in. When you call add-in methods and pass return values that cannot be passed entirely over the stack, the add-in must provide memory using the AllocMemory function of the memory manager. 1C:Enterprise will subsequently free this memory using the FreeMemory function.

IMPORTANT: you cannot allocate memory to return values using "new" or "malloc", as this will lead to a memory leak and application instability.

GetInfo

Syntax:

Copy to clipboard
long GetInfo();

Parameters: none.

Return value:

Description:

1C:Enterprise calls this method to get add-in information. For example, version 3.56 is returned as 3560.

Done

Syntax:

Copy to clipboard
void Done();

Return value: none.

Description:

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

RegisterExtensionAs

Syntax:

Copy to clipboard
bool RegisterExtensionAs(WCHAR_T** wsExtName)

Parameters:

Return value:

Description:

The extension name is assigned to the wsExtName variable. The add-in object provides memory for the string using the AllocMemory memory manager function. 1C:Enterprise frees this memory by calling FreeMemory.

GetNProps

Syntax:

Copy to clipboard
long GetNProps()

Parameters: none.

Return value:

Description:

Returns the number of properties of this extension. Returns 0 if there are no properties.

FindProp

Syntax:

Copy to clipboard
long FindProp(const WCHAR_T* wsPropName);

Parameters:

Return value:

Description:

Returns the sequence number of the property with the pszPropName name. Returns -1 if the property is not found. Properties are numbered starting from 0.

GetPropName

Syntax:

Copy to clipboard
const WCHAR_T* GetPropName(long lPropNum, long lPropAlias)

Parameters:

Return value:

Description:

Returns a property name with the lPropNum sequence number. Returns NULL if no property with that number is found. The add-in object provides memory for the string using the AllocMemory memory manager function. 1C:Enterprise frees this memory by calling FreeMemory.

GetPropVal

Syntax:

Copy to clipboard
bool GetPropVal(const long lPropNum, tVariant* pvarPropVal)

Parameters:

Return value:

Description:

Assigns the value of the property with the lPropNum sequence number to the pvarPropVal variable. If a property with that number is not found or cannot be read, the value must be of the VTYPE_EMPTY type. If the return value is of the string type, the add-in provides memory for it using the AllocMemory function. 1C:Enterprise will free this memory.

SetPropVal

Syntax:

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

Parameters:

Return value:

Description:

The pvarPropVal variable contains a property value with the lPropNum sequence number. If the property with that number does not exist, cannot be saved, or the passed pvarPropVal has an incompatible type, the method returns False.

IsPropReadable

Syntax:

Copy to clipboard
bool IsPropReadable(const long lPropNum)

Parameters:

Return value:

Description:

Returns a Boolean value that indicates whether the property with the lPropNum sequence number is available for reading. False means that the property cannot be read. True indicates that property reading is allowed. If no property with that number is found, the method returns False.

IsPropWritable

Syntax:

Copy to clipboard
bool IsPropWritable(const long lPropNum)

Parameters:

Return value:

Description:

Returns a Boolean value that indicates whether the property with the lPropNum sequence number is available for writing. False means that the property cannot be written. True indicates that property writing is allowed. If no property with that number is found, the method returns False.

Methods are numbered starting from 0. Method parameters are numbered starting from 0.

GetNMethods

Syntax:

Copy to clipboard
long GetNMethods();

Parameters: none

Return value:

Description:

Returns the number of methods of this extension. Returns 0 if there are no methods.

FindMethod

Syntax:

Copy to clipboard
long FindMethod(const WCHAR_T* wsMethodName);

Parameters:

Return value:

Description:

Returns the sequence number of the method with the wsMethodName name. Returns -1 if no method with this name is found.

GetMethodName

Syntax:

Copy to clipboard
const WCHAR_T* GetMethodName(const long lMethodNum, const long lMethodAlias)

Parameters:

Return value:

Description:

Returns the method name with a sequence number. Returns NULL if there is no property with that number. The add-in object provides memory for the string using the AllocMemory memory manager function. 1C:Enterprise frees this memory by calling FreeMemory.

GetNParams

Syntax:

Copy to clipboard
long GetNParams(const long lMethodNum)

Parameters:

Return value:

Description:

Returns the number of parameters of the method with the lMethodNum sequence number. Returns 0 if no method with that number is found or if it does not have any parameters.

GetParamDefValue

Syntax:

Copy to clipboard
bool GetParamDefValue(const long lMethodNum, const long lParamNum, tVariant* pvarParamDefValue)

Parameters:

Return value:

Description:

Assigns the default value of the parameter with the lParamNum number of the method with the lMethodNum sequence number to the pvarParamDefValue variable. Assigns the VTYPE_EMPTY type to the pvarParamDefValue variable if there is no method with that number, no parameter with the number, or the parameter has no default value. If the default value is of the VTYPE_PSTR, VTYPE_PWSTR, or VTYPE_BLOB type, the add-in allocates memory using the AllocMemory memory manager function, writes data there, and saves this address to the corresponding structure field. 1C:Enterprise frees this memory by calling FreeMemory.

HasRetVal

Syntax:

Copy to clipboard
bool HasRetVal(const long lMethodNum)

Parameters:

Return value:

Description:

Returns a Boolean value that indicates whether the method with the lMethodNum sequence number has a return value. True means that the method has a return value. Otherwise, False is returned.

CallAsProc

Syntax:

Copy to clipboard
bool CallAsProc(const long lMethodNum, tVariant* paParams, const long lSizeArray)

Parameters:

Return value:

Description:

Executes the method with the lMethodNum sequence number. If the method returns False, a runtime error occurs and execution of the 1C:Enterprise module is terminated. 1C:Enterprise provides and frees memory for the parameter array.

CallAsFunc

Syntax:

Copy to clipboard
bool CallAsFunc(const long lMethodNum, tVariant* pvarRetValue, tVariant* paParams, const long lSizeArray)

Parameters:

Return value:

Description:

Executes the method with the lMethodNum sequence number. If the method returns False, a runtime error occurs and execution of the 1C:Enterprise module is terminated. 1C:Enterprise provides memory for the parameter array. If the default value is of the string or binary data type, the add-in allocates memory using the AllocMemory memory manager function, writes data there, and saves this address to the corresponding structure field. 1C:Enterprise frees this memory by calling FreeMemory.

Localization

SetLocale

Syntax:

Copy to clipboard
void SetLocale(const WCHAR_T* wsLocale)

Parameters:

Return value:

Description:

(Obsolete. To be used with the platform version 8.3.21 or earlier) 1C:Enterprise calls this method to localize the add-in according to the applied localization code. The add-in can set up its environment to correctly output information.

SetUserInterfaceLanguageCode

Syntax:

Copy to clipboard
void SetUserInterfaceLanguageCode(const WCHAR_T* wsLanguageCode)

Parameters:

Description:

1C:Enterprise passes the two-letter language code used by the user interface to the add-in.

 

1C:Enterprise interface

When the add-in object is initialized, a pointer to 1C:Enterprise interface is passed to it, which you can use to call the methods listed below. Note that these methods are not operable on the application server.

AddError

Syntax:

Copy to clipboard
bool AddError(unsigned short wcode, const WCHAR_T* source, const WCHAR_T* descr, long scode)

Parameters:

Return value:

Description:

Adds an informational message when language extension methods are running. If the return value is True, the error information has been added successfully. If scode has a non-zero value, an exception, which can be programmatically caught and processed, is thrown.

Possible message codes and 1C:Enterprise behavior are described in detail in the Informational messages about the object operation section for COM add-ins.

RegisterProfileAs

Syntax:

Copy to clipboard
bool RegisterProfileAs(WCHAR_T* wsProfileName)

Parameters:

Return value:

Description:

Registers a list with add-in parameters with the wsProfileName name.

Read

Syntax:

Copy to clipboard
bool Read(WCHAR_T* pszPropName, tVariant* pVal, long* pErrCode, WCHAR_T** errDescriptor)

Parameters:

Return value:

Description:

Reads the saved value of the add-in parameter with the pszPropName name. If an error occurs when reading and errDescriptor is a non-zero value, 1C:Enterprise provides memory and assigns error description. The add-in must free memory by calling FreeMemory. For returned data of the string type, memory is also provided by 1C:Enterprise, and the address is saved to the corresponding field of the tVariant structure. The add-in must free it by calling FreeMemory.

Write

Syntax:

Copy to clipboard
bool Write(WCHAR_T* pszPropName, tVariant* pVar)

Parameters:

Return value:

Description:

Saves the add-in parameter value with the pszPropName name. If the attempt is not successful, False is returned.

SetEventBufferDepth

Syntax:

Copy to clipboard
bool SetEventBufferDepth( long lDepth)

Parameters:

Return value:

Description:

Sets the event queue size for this object. If the current number of events in the queue is greater than the set length, the latest events are removed.

GetEventBufferDepth

Syntax:

Copy to clipboard
long GetEventBufferDepth()

Parameters: none

Return value:

Description:

Returns the event queue size for this object.

ExternalEvent

Syntax:

Copy to clipboard
bool ExternalEvent(WCHAR_T* wsSource, WCHAR_T* wsMessage, WCHAR_T* wsData)

Parameters:

Return value:

Description:

Queues an event and records its source, name, and parameters. During event processing, this data is passed to the ExternEventProcessing procedure. When you call the ExternalEvent method, event processing looks as follows: the event is written to the event queue (if the queue is full, the event is lost). After that, if there are no system events, the first event is taken from the queue (if the queue is not empty) and external event processing is triggered. This process is repeated for all add-in objects. This way, processing of external events is synchronized with processing of system events.

CleanEventBuffer

Syntax:

Copy to clipboard
void CleanEventBuffer()

Description:

Clears the event queue by removing all events in the queue.

SetStatusLine

Syntax:

Copy to clipboard
bool SetStatusLine(WCHAR_T* wsStatusLine)

Parameters:

Return value:

Description:

Sets the status line text.

ResetStatusLine

Syntax:

Copy to clipboard
void ResetStatusLine()

Return value:

None

Description:

Initializes the status line.

GetInterface

Syntax:

Copy to clipboard
IInterface* GetInterface(Interfaces iface)

Parameters:

Return value:

Description:

Requests the platform interface. If the platform supports the requested interface, a pointer to the interface is returned. Otherwise, 0 is returned.

Confirm

Syntax:

Copy to clipboard
bool Confirm(const WCHAR_T* queryText, tVariant* retVal)

Parameters:

Return value:

Description:

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

Alert

Syntax:

Copy to clipboard
bool Alert(const WCHAR_T* text)

Parameters:

Return value:

Description:

Displays a simple notification dialog box with a text defined by the text parameter and with an OK button.

GetPlatformInfo

Syntax:

Copy to clipboard
AppInfo* GetPlatformInfo()

Return value:

Description:

Requests information on the platform. When you attach the add-in in the web client of the platform version earlier than 8.3.3, only the Application field of the AppInfo structure will be filled.

GetAttachedInfo

Syntax:

Copy to clipboard
AttachedType GetAttachedInfo()

Return value:

Description:

Requests information on the add-in attachment type.

 

Correspondence between tVariant and 1C:Enterprise types

Correspondence between 1C:Enterprise and COM types:

The VTYPE_INTERFACE and VTYPE_VARIANT types are not supported.

Note:
Numeric values passed as parameters from the web client can be received with any numeric type.

The VTYPE_BLOB type is not supported in the web client.

Specifics of add-in development using Native API

Any add-in created using this technology is platform-dependent. So, the developer must build an add-in version for both x86 and x86-64 platforms, as well as for ARM64, and Elbrus-8C. Later, the configuration developer will determine the platform type and import the required add-in variant.

The add-in must be supported by all operating systems from the list of supported operating systems. We recommend that you build add-ins for Linux on the latest supported Linux version from the list.

Also, note that you can import add-ins on the 1C:Enterprise application server running any OS. For this reason, it is recommended that you make your add-in cross-platform.

1C:Enterprise operates with strings in Unicode format (WCHAR_T) with 2 byte characters. The character size matches the built-in wchar_t type for Windows, but may differ for other OS. The wchar_t size in other OS may be, for example, 4 bytes. The add-in developer must manually convert character data of this type.

If an add-in uses additional modules, specify it in the add-in documentation. Statically add applied non-system run-time libraries to the add-in if it is permitted by the run-time library license. You need to do it as the libraries might be missing or have inappropriate version on the computer where the add-in will be used. Also include a manifest in the Windows add-in.

If exceptions are thrown, they must be caught and processed in the add-in. Information about them must be passed to 1C:Enterprise by the AddError method.

If the add-in is used on the 1C:Enterprise application server, external events are not processed. Methods related to status line operations and saving parameters will not be processed as well.

The add-in can return any binary data, for example, a generated barcode image. For that, data is assigned to the pstrVal field of the tVariant structure, the data size is assigned to strLen, and the type is assigned to VTYPE_BLOB. 1C:Enterprise uses the BinaryData type for them.

The date value is passed to the add-in as the tm structure with specified VTYPE_TM type. The add-in can return a date value either in struct tm or Windows DATE type with specified VTYPE_DATE type. 1C:Enterprise will process it correctly.

Return values of the VTYPE_ARRAY and VTYPE_BYREF types are not supported.

Web publishing settings for the mobile 1C:Enterprise platform

When you configure Web publishing, add MIME types in http server settings for the following extensions:

MIME type: application/octet-stream

Windows Runtime

For development on Windows Runtime, you need Windows 8.1 or later installed with MS Visual Studio 2017 (Windows Phone SDK kit).

Add-in development result must be a group of dynamic *.dll libraries for mobile phones and tablets of all supported processors.

You can find add-in project examples in the \example\NativeAPIMobile\WinRT_Proj\ directory.

To debug add-ins, use projects in the mobile.zip\Windows\vcproj.zip distribution package:

Before using any of them, copy the content of 1cem-XXXXX.appx distribution package archive to the appx\ directory.

After adding the source codes of your add-in, you can use standard MS Visual Studio tools for debugging.

Windows Runtime does not support import of dynamic libraries from a Web publication.

Android

On Android, you can write a code in C++  and use Java Native Interface technology.

Add-in development result for Android must be a group of *.so dynamic libraries for all supported processors. For Java code, the result must also include an *.apk file. The *.apk file is not a separate application and is not designed to run independently. It is further included in the built mobile application.

You can find a project example in the \example\NativeAPIMobile\Android_Proj\ directory.

To debug an add-in, use dynamic libraries imported from a Web publication. This import is performed automatically after updating the configuration (with nested libraries) on the device with the web publication on the developer's computer.

iOS

In case of iOS application development, you cannot use non-system dynamic libraries for publishing in AppStore. For that reason, the add-in developer must use them only for development and debugging purposes.

Add-in development result for iOS must include a file of dynamic *.dylib library for testing purposes signed with a developer certificate and a binary *.a file for static linking for the application builder.

To debug an add-in, use the project  in the mobile.zip\iOS\prjios.zip distribution package.

After adding the source codes of your add-in, you can use standard Xcode tools for debugging.

To debug an add-in, you can also import dynamic libraries from a Web publication. This import is performed automatically after updating the configuration (with nested libraries) on the device with the Web publication on the developer's computer.

iOS 10.0 and later versions no longer support using dynamic libraries from a web publication. In this case, you can use the binary file of static *.a library for testing purposes.

Signing with a developer certificate

Signing with a developer certificate is performed using the codesign utility with the following command:

codesign -s <certificate name> <library file name>

Example:

Copy to clipboard 
codesign -s "iPhone Developer" /Users/Somebody/Documents/addin/iOS_Proj/Build/com_1c_StepCounter.dylib

Static library

With the static *.a library, you can build the final application by linking an add-in into the platform.

To avoid name conflicts, the add-in code must be located in its own unique namespace. The namespace name must match or include the add-in name.

The add-in is registered statically when the application is loaded. You can see the respective code in the example.

Copy to clipboard 
#if defined(__APPLE__) && !defined(BUILD_DYNAMIC_LIBRARY)

namespace COM_1C_STEP_COUNTER
{  
    static LPCVOID addin_exports[] =
    {
        "GetClassObject", (LPCVOID)GetClassObject,
        "DestroyObject", (LPCVOID)DestroyObject,
        "GetClassNames", (LPCVOID)GetClassNames,
        "SetPlatformCapabilities", (LPCVOID)SetPlatformCapabilities,
        NULL
    };
    DECLARE_DLL((const char*)g_kComponentNames, addin_exports);
}

#endif //__APPLE__ && !BUILD_DYNAMIC_LIBRARY

 

You can find a project example in the \example\NativeAPIMobile\iOS_Proj\ directory.

Creating add-ins using COM

You can apply add-ins created using COM in earlier 1C:Enterprise versions (7.7, 8.0, and 8.1).

However, you cannot create add-ins using this technology for Microsoft Windows Runtime, Android, or iOS.

When you import an add-in by the LoadAddIn or AttachAddIn function (<AddInLocation>, <MarkName>, AddInType.COM), 1C:Enterprise identifies ProgID of the add-in COM object in the following way:

When you use the AttachAddIn function (<AddInObjectName>), ProgID of the add-in COM object is passed as the function parameter. It can also be presented as a string in the ProgID1| ProgID2|...|ProgIDX format.

Initializing and exporting add-ins

To initialize and export an add-in, use the IInitDone interface. This interface is inherited from IUnknown. Use it to initialize an object and complete operations with it.

Init

Syntax:

Copy to clipboard
HRESULT Init(IDispatch *pBackConnection)

Parameters:

Return value:

Description:

Upon import, 1C:Enterprise initializes the add-in object by calling the Init method and passing a pointer to IDispatch. The object can save this pointer to use it later. To get other 1C:Enterprise interfaces, the object calls the QueryInterface method of the received IDispatch interface. If the object returns S_OK, the initialization succeeded. If the object returns E_FAIL, an error occurred. The method can use the IerrorLog interface to display error details. The initialization is unsuccessful if the scode field in one of the passed EXCEPINFO structures is not S_OK. All data passed to IErrorLog is processed when returning from this method. The AppDispatch property is undefined when the method is called.

Done

Syntax:

Copy to clipboard
HRESULT Done(void) 
Return value: 
Description:
1C:Enterprise calls this method when operation with an
add-in object is completed. The object must return S_OK. This method is called
regardless of the object initialization result (Init method). 
GetInfo 
Syntax: 
Copy to clipboard
HRESULT GetInfo(SAFEARRAY** pInfo) 
Parameters: 
Return value: 
Description:
1C:Enterprise calls this method to get add-in
information. For the current add-in technology version 2.0, write the supported
add-in technology version in the item with index 0. The version value must be
an integer in V_14 format. Major version number is in thousands place and minor
version number is in units place. For example, version 3.56 is returned as
3560. Currently, all add-in objects support version 1.0 (the number is 1000) or
version 2.0 (the number is 2000). 1C:Enterprise provides memory for pInfo. The
method must return S_OK. 
The add-in object must implement the interface. If the
interface is not found, you cannot import the add-in.
1C:Enterprise language extension
To extend 1C:Enterprise language, the add-in must
implement the ILanguageExtender interface. The interface is inherited from IUnknown. It is intended to extend 1C:Enterprise language. To use this
extension, call the CreateObject function (New in 1C:Enterprise 8) and pass a
string in the "AddIn.<ExtensionName>" format to the function,
where <ExtensionName> is the return value of the interface method. After
that, you can use the created object by calling its methods and properties.
With version 2.0, you can create multiple objects of the
same "AddIn.<ExtensionType>" type. However, it is possible only
if version 2.0 support is explicitly specified for the add-in in the GetInfo method. Otherwise, you can create only one object.
RegisterExtensionAs 
Syntax:
Copy to clipboard
HRESULT RegisterExtensionAs(BSTR *pExtensionName) 
Parameters: 
Return value:
Description:
Assigns an extension name to the pExtensionName variable.
The add-in object uses standard system functions for COM string operations to
provide memory for the string (for example, SysAllocString). To clear the
memory, 1C:Enterprise calls SysFreeString.
GetNProps 
Syntax: 
Copy to clipboard
HRESULT GetNProps(long* plProps) 
Parameters: 
Return value: 
Description:
Returns the number of properties of this extension.
Returns 0 if there are no properties. 1C:Enterprise provides memory for the plProps variable.
FindProp 
Syntax:
Copy to clipboard
HRESULT FindProp(BSTR pszPropName,long* plPropNum) 
Parameters: 
Return value: 
Description:
Returns the sequence number of the property with the pszPropName name. Returns -1 if the property is not found. Properties are
numbered starting from 0. 1C:Enterprise provides memory for the plPropNum variable. 
GetPropName 
Syntax:
Copy to clipboard
HRESULT GetPropName(long lPropNum,long lAliasNum,BSTR* pPropName) 
Parameters: 
Return value: 
Description:
Assigns the name of the property with the lPropNum sequence number to the pPropName variable. If no property with this number is
found, an empty string is assigned to pPropName. The add-in object uses
standard system functions for COM string operations to provide memory for the
string (for example, SysAllocString). To clear the memory, 1C:Enterprise calls SysFreeString.
GetPropVal
Syntax:
Copy to clipboard
HRESULT GetPropVal(long lPropNum,VARIANT* pvPropVal) 
Parameters:
Return value:
Description:
Assigns the value of the property with the lPropNum sequence number to the pvPropVal variable. If a property with that number is
not found or cannot be read, the variable must be of the VT_EMPTY type. 
SetPropVal
Syntax:
Copy to clipboard
HRESULT SetPropVal(long lPropNum, VARIANT* pvPropVal) 
Parameters: 
Return value: 
Description:
The pvPropVal variable contains the value of the property
with the lPropNum sequence number. The method returns S_FALSE if the property
with this number is not found or unavailable for recording or when the type of
passed pvPropVal cannot be converted to the required one. 
IsPropReadable 
Syntax: 
Copy to clipboard
HRESULT IsPropReadable(long lPropNum, BOOL* pboolPropReadable) 
Parameters: 



Return value: 
Description:
Assigns a Boolean value that indicates whether the
property with the lPropNum sequence number is available for reading to the pboolPropReadable variable. FALSE(0) means that the property cannot be read.
TRUE(1) indicates that property reading is allowed. If no property with this
number is found, the method returns S_FALSE. 
IsPropWritable 
Syntax: 
Copy to clipboard
HRESULT IsPropWritable(long lPropNum, BOOL* pboolPropWritable) 
Parameters: 



Return value: 
Description:
Assigns a Boolean value that indicates whether the
property with the lPropNum sequence number is available for recording to the pboolPropReadable variable. FALSE(0) means that the property cannot be
recorded. TRUE(1) indicates that property recording is allowed. If no property
with this number is found, the method returns S_FALSE. 
Methods are numbered starting from 0. Method parameters
are numbered starting from 0.
GetNMethods 
Syntax: 
Copy to clipboard
HRESULT GetNMethods(long* plMethods) 
Parameters: 
Return value:
Description:
Assigns the number of extension methods to the plMethods variable. Assigns 0 if there are no methods. 
FindMethod 
Syntax: 
Copy to clipboard
HRESULT FindMethod(BSTR bstrMethodName, long* plMethNum) 
Parameters: 
Return value:
Description:
Assigns the sequence number of the bstrMethodName method to the plMethNum variable. If the method is not found, -1 is assigned to the variable. 
GetMethodName 
Syntax:
Copy to clipboard
HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR* pbstrMethName) 
Parameters: 
Return value:
Description:
Assigns a method name with a sequence number to the pbstrMethName variable. Assigns an empty string if no property with this number is found. The add-in object uses standard system functions for COM string operations to provide memory for the string (for example, SysAllocString). To clear the memory, 1C:Enterprise calls SysFreeString. 
GetNParams 
Syntax:
Copy to clipboard
HRESULT GetNParams(long lMethodNum, long* plMethParams) 
Parameters: 
Return value: 
Description:
Assigns the number of parameters of the method with the lMethodNum sequence number to the plMethParams variable. Assigns 0 if the
method with this number is not found or has no parameters. 1C:Enterprise
provides memory for the variable. 
GetParamDefValue 
Syntax:
Copy to clipboard
HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT* pvParamDefVal) 
Parameters: 
Return value: 
Description:
Assigns the default value of the lParamNum parameter of
the method with the lMethodNum sequence number to the pvParamDefVal variable.
Assigns the VT_EMPTY type to pvParamDefVal if the method with this number is
not found or has no parameter with a number or when the parameter has no
default value. 1C:Enterprise provides memory for the variable. 
HasRetVal 
Syntax:
Copy to clipboard
HRESULT HasRetVal(long lMethodNum,BOOL* pboolHasRetVal) 
Parameters: 
Return value: 
Description:
Assigns a Boolean value that indicates whether the method
with the lMethodNum sequence number has a return value to the pboolHasRetVal variable. TRUE means that the method has a return value. Otherwise, the return
value is False. 1C:Enterprise provides memory for the variable. 
CallAsProc 
Syntax:
Copy to clipboard
HRESULT CallAsProc(long lMethodNum, SAFEARRAY** pVars) 
Parameters: 
Return value: 
Description:
Executes the method with the lMethodNum sequence number.
If the method returns E_FAIL, a runtime error occurs and 1C:Enterprise module
execution is terminated. 1C:Enterprise provides memory for the parameter array. 
CallAsFunc 
Syntax:
Copy to clipboard
HRESULT CallAsFunc(long lMethodNum, VARIANT* pRetValue, SAFEARRAY** pVars) 
Parameters: 
Return value: 
Description:
Executes the method with the lMethodNum sequence number.
If the method returns E_FAIL, a runtime error occurs and 1C:Enterprise module
execution is terminated. 1C:Enterprise provides memory for the array. 
Localization
SetLocale 
Syntax:
Copy to clipboard
HRESULT SetLocale(BSTR bstrLocale) 
Parameters:
Return value: 
Description:
(Obsolete. To be used with the platform version 8.3.21 or
earlier) 1C:Enterprise calls this method to localize the add-in according to
the applied localization code. The add-in can set up its environment to
correctly output information. 
SetUserInterfaceLanguageCode 
Syntax:
Copy to clipboard
HRESULT SetUserInterfaceLanguageCode(BSTR wsLanguageCode) 
Parameters:
Return value: 
Description:
1C:Enterprise passes the two-letter language code used by
the user interface to the add-in.
Using the COM VARIANT type for data
exchange
Calling an add-in function
Correspondence between 1C:Enterprise and COM types:
Note that the internal presentation can be more precise
than the double type (about 15 decimal places). That is why the value might be
less precise after conversion.
When converting a COM object to IDispatch, mutual call
situations "1C:Enterprise > Add-in > 1C:Enterprise" and
"Add-in > 1C:Enterprise > Add-in" are checked, and all required
operations are performed correctly.
Returning values from add-ins 



Correspondence between 1C:Enterprise and COM types:
The VT_DECIMAL, VT_VARIANT, and VT_UNKNOWN types are not
supported.
When converting IDispatch to a COM object, mutual call
situations "1C:Enterprise > Add-in > 1C:Enterprise" and
"Add-in > 1C:Enterprise > Add-in" are checked, and all required
operations are performed correctly.
Calling 1C:Enterprise object methods
from add-ins
To call an object method, call the Invoke method of the IDispatch interface received earlier and pass all required parameters including
the number (DISPID) of the called object method to the interface. You can get
the number from the GetIDsOfNames method of the IDispatch interface. To do so,
pass the object method name to the interface.
Correspondence between object method parameters and the
VARIANT structure array is direct. It means that the structure with index 0
corresponds to the first parameter, the structure with index 1 corresponds to
the second parameter, and so on. When passing object method parameters, ensure
that you pass values of all parameters including the default parameter values.
To specify default values, assign the VT_EMPTY type (VT_ERROR for 1C:Enterprise
8) to the corresponding VARIANT structure.
 



1C:Enterprise COM-interfaces
To get each of the interfaces mentioned below, call QueryInterface from the IDispatch pointer object passed upon initialization.
You can find their IDs (IID) in the templates included in this distribution
package.
Saving
add-in object parameters 
To save parameters, an add-in object can use
1C:Enterprise methods of saving via the IPropertyProfile interface. This
interface is inherited from the IPropertyBag interface that is standard for COM
and has only one different method:
RegisterProfileAs 
Syntax:
Copy to clipboard
HRESULT RegisterProfileAs(BSTR bstrProfileName) 
Parameters: 
Return value: 
Description:
Registers a list of parameters of the bstrProfileName add-in. 
You can arrange parameters as a tree when importing and
saving them. To do so, specify the parameter name as
"Node1\Node2\...\NodeN\ParameterName:ParameterDefaultValue" when
passing in the Read and Write methods. In 1C:Enterprise 7.5, parameters are
saved to the system registration database (Registry) in the HKEY_CURRENT_USER\Software\1C\1Cv7\7.5\Options key. In 1C:Enterprise 7.7, they are
saved in the HKEY_CURRENT_USER\Software\1C\1Cv7\7.7\Options key. In
1C:Enterprise 8, they are saved to a profile corresponding to "computer – infobase – user".
Informational messages on object
operation
To inform a user about its operations, an object can use
the IErrorLog interface, which is standard for COM. The AddError method of the IErrorLog interface is described here for operation convenience only. Emerging
messages are processed when the application is running (if the messages are
queued asynchronously). They are also processed when returning from the Init
initialization method and the extension method. All messages are queued and
processed in the order they appear. The number of memorized messages is
unlimited.
AddError 
Syntax:
Copy to clipboard
HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo)
Parameters: 
Return value: 
Other return codes might be displayed to indicate an
error.
Description:
Adds an informational message when language extension
methods are running. 



Possible message codes:
Copy to clipboard


#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 assigned to the wCode field of the
EXEPINFO structure. Error codes 1000 – 2000 are reserved.
When you process the message, a message box is displayed
for the ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO, and ADDIN_E_MSGBOX_FAIL
codes, or a string with a message in the message box for the other codes. In
general, the string has the following format:
<Icon> <MessageSource> :
<MessageDescription> (MessageCode = <MessageCode>),
where <Icon>:



The icon is missing if the used message code does not
match the ones listed above.
<ErrorSource> : the bstrSource field in the
EXCEPINFO structure
<ErrorDescription> : the bstrDescription field in
the EXCEPINFO structure
<ErrorCode> : numeric message code in decimal form.
The message code is not displayed if one of the above codes is used.
For the ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO,
and ADDIN_E_MSGBOX_FAIL codes, a message box is displayed with the OK button
and the MB_ICONEXCLAMATION, MB_ICONINFORMATION, and MB_ICONERROR icons
respectively.
The message has the following format:
Copy to clipboard
<MessageSource>:<MessageDescription>(Message code = <MessageCode>),
where <MessageSource>, <MessageDescription>,
and <MessageCode> are described above.
Dialog box messages
To display a dialog box to the user, the object can use
the IMsgBox interface, which is standard for COM. The IMsgBox interface is
inherited from IUnknown. Not available on the server and in an external
connection.
Confirm
Syntax:
Copy to clipboard
HRESULT Confirm(const BSTR queryText, VARIANT* retVal); 
Parameters:
Return value:
Description:
Displays a dialog box with a text specified in the queryText parameter and OK and Cancel buttons.
Alert
Syntax:
Copy to clipboard
HRESULT Alert(BSTR text)
Parameters:
Return value:
Description:
Displays a simple dialog box with the OK button.
Platform information
To receive information about the application that
attached the object, you can use the IPlatformInfo interface, which is standard
for COM. The IPlatformInfo interface is inherited from IUnknown
GetPlatformInfo
Syntax:
Copy to clipboard
HRESULT GetPlatformInfo(AppInfo** info)
Parameters:
Return value:
Description:
Requests information on the platform. When you attach the
add-in in the web client of the old platform version, only the Application
field of the AppInfo structure will be filled.
GetAttachedInfo
Syntax:
Copy to clipboard
HRESULT GetAttachedInfo(AttachedType** type)
Parameters:
Return value:
Description:
Requests information on the add-in attachment type. 



External events
When an asynchronous event occurs (for example, reading a
barcode), the object can use the IAsyncEvent interface to create an external
event in 1C:Enterprise. The IAsyncEvent interface is inherited from IUnknown.
All events are queued and processed in the order they appear. The number of
stored events is limited by the queue length. Upon initialization, the queue
length is set to 1 and can be changed by calling SetEventBufferDepth, and the
current queue size is received using the GetEventBufferDepth method. Each
add-in object supports its own event queue. An external event is processed
using the predefined ExternEventProcessing procedure and external event
handlers in form modules.
SetEventBufferDepth 
Syntax:
Copy to clipboard
HRESULT SetEventBufferDepth(long lDepth) 
Parameters: 



Return value: 
Other return codes might be displayed to indicate an
error.
Description:
Sets the event queue size for this object. If the current
number of events in the queue is greater than the set length, the latest events
are removed. 
GetEventBufferDepth 
Syntax:
Copy to clipboard
HRESULT GetEventBufferDepth(long* plDepth) 
Parameters: 
Return value: 
Other return codes might be displayed to indicate an
error.
Description:
Assigns the event queue size for this object to the plDepth variable. 
ExternalEvent 
Syntax:
Copy to clipboard
HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData)
Parameters: 
Return value: 
Other return codes might be displayed to indicate an
error.
Description:
Queues an event and records its source, name, and
parameters. During event processing, this data is passed to the ExternEventProcessing procedure. When you call the ExternalEvent method, event
processing looks as follows: the event is written to the event queue (if the
queue is full, the event is lost). After that, if there are no system events,
the first event is taken from the queue (if the queue is not empty) and
external event processing is triggered. This process is repeated for all add-in
objects. This way, processing of external events is synchronized with
processing of system events. 
CleanBuffer 
Syntax:
Copy to clipboard
HRESULT CleanBuffer() 
Return value: 
    
 
  • 
	S_OK: the queue is successfully
     cleared. 
  • 
	E_FAIL: an error occurred when
     clearing the queue. 
Other return codes might be displayed to indicate an
error.
Description:
Clears the event queue by removing all events in the
queue. 
Status line operations 
The add-in object can use the IStatusLine interface to
inform the user of its state. When you call the SetStatusLine method, the
passed text is immediately displayed in the status line. When you call the ResetStatusLine method, the status line displays the standard text.
SetStatusLine 
Syntax:
Copy to clipboard
HRESULT SetStatusLine(BSTR bstrStatusText) 
Parameters: 



    
 
  • 
	<bstrStatusText> Type: BSTR.
     Status line text. 
Return value: 
    
 
  • 
	S_OK: the text is displayed in the
     status line. 
  • 
	E_FAIL: an unknown error occurred. 
Other return codes might be displayed to indicate an
error.
Description:
Sets the status line text. 
ResetStatusLine 
Syntax:
Copy to clipboard
HRESULT ResetStatusLine() 
Return value: 
    
 
  • 
	S_OK: the status line is
     successfully reinitialized. 
  • 
	E_FAIL: an unknown error occurred.
Other return codes might be displayed to indicate an
error..
Description:
Initializes the status line. 



Creating windows in 1C:Enterprise 8
environment 



Add-ins can create their own windows to display various
information using the IExtWndsSupport interface. The add-in can create
two types of windows: modal dialog boxes and modeless dialog boxes.
Modal dialog boxes 
Modal dialog boxes are created by the add-in. However,
when creating them, specify the window returned by the GetAppMainFrame method
as the parent window so that the operating system does not perceive the dialog
box as a separate task with a button on the taskbar. 1C:Enterprise operation is
suspended until the dialog box operation is completed.
Modeless dialog boxes  



Modeless dialog boxes are also created by the add-in.
However, when creating them, specify the window returned by the GetAppMDIFrame method as the parent window so that the operating system does not perceive the
dialog box as a separate task with a button on the taskbar. The dialog box does
not stop the operation of 1C:Enterprise and is similar to 1C:Enterprise forms.
However, note that the created dialog box is not included in the list of open
windows and is not displayed on the window panel. Therefore, using such dialog
boxes is not recommended (you can use 1C:Enterprise forms instead).
In 1C:Enterprise 8, the ability to create windows is
preserved with limitations for compatibility with the existing add-ins. To
display non-standard information in 1C:Enterprise 8 windows, we recommend that
you use forms with ActiveX controls or Active documents. Methods of the IExtWndsSupport interface are described below. Window operations are not
supported in the web client.
GetAppMainFrame 
Syntax:
Copy to clipboard
HRESULT GetAppMainFrame(HWND* pHWnd) 
Parameters: 
    
 
  • 
	<pHWnd> Type: HWND*. Pointer to the window descriptor 
Return value: 
    
 
  • 
	S_OK: successfully completed. 
  • 
	E_FAIL: an error occurred.
Description::
Returns the main 1C:Enterprise window descriptor. 
GetAppMDIFrame 
Syntax:
Copy to clipboard
HRESULT GetAppMDIFrame(HWND* pHWnd) 
Parameters: 
    
 
  • 
	<pHWnd> Type: HWND*. Pointer to the window descriptor 
Return value: 
    
 
  • 
	S_OK: completed successfully. 
  • 
	E_FAIL: an error occurred.
Description:
Returns the active 1C:Enterprise window descriptor. 



Accessing 1C:Enterprise via OLE
Automation 



Technology version: 2.0
The pointer to IDispatch passed in the Init method allows
you to access 1C:Enterprise via OLE Automation. From the received pointer, you
can get the read-only AppDispatch property. This property contains a pointer to IDispatch of 1C:Enterprise (do not confuse it with the one passed to Init).
When the add-in is attached to the web client, the AppDispatch property will be
unavailable. Consider it when developing add-ins.
The AppDispatch property becomes available only after the
entire 1C:Enterprise system is fully initialized. For that reason, when the
add-in is being loaded and the Init method is called, this property does not
provide access to all 1C:Enterprise features.
Accessing 1C:Enterprise interface methods via OLE
Automation
Visual Basic has a limited functionality for operation
with various interfaces. In Visual Basic, you can operate with OLE Automation
via the Object type, which is a pointer to IDispatch. In 1C:Enterprise, you can
use OLE Automation by passing a pointer to IDispatch in the Init method and
ensuring calls to methods of the above interfaces via OLE Automation.
Methods and properties available via
OLE Automation
Technology version: 1.0
RegisterProfileAs(<ParametersListName>)
Read(<VariableName>,<RefToVARIANT>)
Write(<VariableName>,<RefToVARIANT>)
SetEventBufferDepth(<EventsQueueLength>)
GetEventBufferDepth(<RefToQueueLength>)
ClearEventBuffer()
ExternalEvent(<StringEventSource>,<StringEventName>,<StringEventParameters>)
AddError(<MessageCode>,<StringMessageSource>,<StringMessageDescription>,<ErrorCode>)
SetStatusLine(<StatusLine>)
ResetStatusLine()
Technology version: 2.0 (additional to version 1.0)

Important. The methods and properties listed below are unavailable in the web client:
    
 
  • 
	AppDispatch property 
  • 
	GetAppMainFrame(<Pointer to the
     window descriptor>) 
  • 
	GetAppMDIFrame(<Pointer to the
     window descriptor>) 
Specifics of add-in development using
COM
Add-ins developed using COM technology may not be
initially installed on the user's computer. The AttachAddIn(<AddInLocation>,
<MarkName>, AddInType.COM) method gets the add-in file from the infobase if the latter is located there and calls the DllInstall add-in object
registration function. If user registration is not successful, the DllRegisterServer function is called. If the user has restricted rights, add-in
registration and attachment might be unsuccessful. The developer must ensure
successful add-in registration for users under their current rights. If an
add-in has its own installer, it must be registered for the computer.
Preparing
add-ins for web client operations
The web client interacts with add-ins over extensions.
You can find projects for building extensions for Firefox, Google Chrome,
Internet Explorer, and Safari in the provided examples. For security reasons,
each extension can process only one add-in specified at the compilation stage.
Every extension consists of an add-in and browser adapter. An add-in that is
already created using COM can serve as the add-in component. 
For Windows and Mac X, the developer must digitally sign
the distribution package and all executable files included in it. According to
Microsoft recommendations, all Windows distribution packages,
except for msi packages, must have two signatures: sha1 and sha256.
Browser scripting language is single-threaded. That is
why you must avoid callbacks from any threads other than the add-in main
thread. Only the following methods will function in other threads: ExternalEvent, SetStatusLine, and ResetStatusLine. Keep it in mind when you
develop an add-in.
On Windows, browser libraries use the Visual Studio 2017
compiler with Windows XP support. 
Starting from platform version 8.3.6, one adapter is used
for Mozilla Firefox and Google Chrome.
Add-ins
for Internet Explorer
Creating an adapter for Internet Explorer
A developer can create an extension based on the AddInIE project from the example directory. In the idl file, change the library name
(for example, library MyComponentIELib) and coclass and library uuid. All file
changes the developer must make are marked with the "//change"
comment. You do not need to change interface uuid and names. It is recommended
that you rename the project (for example, MyComponentIE). In the config.cpp file, replace the name of the included AddInIE_i.h file with the name generated
by the idl file development environment. Also, change text variable values to
library coclass names (for example, MyComponentIE.AddInServiceEx). Assign your
library's LIBID value to the LIBID_AddInWebLib variable. In the nameFileComponent variable, specify the add-in name (for example, AddInNative.dll). In the nameFilePrj variable, specify the name of the
extension project output file (for example, MyComponentIE.dll). An extension
for Internet Explorer is a COM object, so the developer must pay attention to Specifics of add-in development using COM.
Creating a distribution package for Internet Explorer
Starting from 1C:Enterprise version 8.3.12, a
distribution package for Internet Explorer in Microsoft Windows is created in
the EXE format. In the example\AddInIESetup directory, you can find the NSIS project that creates a distribution package for an add-in example. To build a
project, install NSIS. In the AddInIESetup.nsh file, set values for each
add-in. If you want to use add-ins with earlier 1C:Enterprise versions, create
the distribution package as a CAB file. To see the script for building the CAB
file, open example\PackageIE\buildcab.bat.
Add-ins for Google Chrome and Mozilla
Firefox
Creating an adapter for Google Chrome
and Mozilla Firefox
An add-in adapter for Google Chrome is a console
application. Upon installation, the adapter registers one or multiple unique
extension names in the browser. It is recommended that the extension name
starts with "com." and includes the add-in version number. For
example, "com.YourCompanyName.YouAddInName.1". If a new add-in
version is released, update the version number in the name. Otherwise, the web
client will continue using the old add-in version.
For example, suppose that the configuration uses an
add-in named "com.YourCompanyName.YouAddInName.3". The developer
releases a new add-in version. To include it in the configuration, you must
rebuild adapters for Google Chrome by renaming them to
"com.YourCompanyName.YouAddInName.4". Then rebuild distribution
packages and include them in the 
archive to import
to the configuration. Change the archive
manifest file name to com.YourCompanyName.YouAddInName.4. After that, import
the archive to the configuration. What happens when you start the web client
with a new configuration on the device where the previous add-in version is
installed? The web client receives the
"com.YourCompanyName.YouAddInName.4" add-in name from the the
configuration. This extension name is not registered in the browser, so the old
add-in version will not be used. To use the add-in, the user must install it.
However, the old version is not deleted. It remains available for use with
earlier configurations.
The developer can create an extension based on the AddInChrome project from the example directory. In the config.cpp file, change
values of the nameFilePrj and nameFileComponent variables. nameFilePrj must
contain the adapter file name (for example, AddInChrWin32.exe). nameFileComponent must contain the add-in file name (for example, AddInNative.dll).
The jsoncpp library (license) is used in adapters.
Creating a distribution package for
Google Chrome.
A distribution package for Google Chrome on Windows is
created in the EXE format.
A distribution package must include:
    
 
  • 
	Add-in file 
  • 
	Add-in adapter file 
  • 
	Manifest file (in JSON format). 
The manifest file must look as follows:
Copy to clipboard
{

"name": "com.YourCompanyName.YouAddInName",

"description": "Description of add-in for Chrome and
Firefox",

"path": "AddInChr.exe",

"type": "stdio",

"allowed_origins": [

"chrome-extension://pbhelknnhilelbnhfpcjlcabhmfangik/"

]

}
In the manifest file, change the following:



	Name



	Description
nameExtension
  name
descriptionDisplayed
  add-in description
pathPath to the
  add-in adapter file
Do not change the rest of the attributes.
When installing, the package copies files to the computer
hard drive and registers the extension as a browser plugin in the system
registry. In the registry, create the HKCU\Software\Google\Chrome\NativeMessagingHosts\com.YourCompanyName.YouAddInName branch (replace YourCompanyName and YouAddInName with your values). In the
branch, create a parameter that shows the full path to the manifest file. The
parameter must be of the default string type. The 'name' attribute of the
manifest must match the registry branch name.
The developer must digitally sign the package
(SHA1+SHA256).
In the example\AddInChromeSetup folder, you can find the NSIS project that creates a distribution package for an add-in example. To
build a project, install NSIS. In the AddInChromeSetup.nsh file, set values for each add-in.
The distribution package for Google Chrome and Firefox on
Linux is created as a self-extracting archive. It contains binary add-in
modules, an adapter, and a manifest file. You can use the makeself utility to build an archive. The archive script must copy the manifest to
the ~/.config/google-chrome/NativeMessagingHosts/ directory. It also must copy
executable files to another location.
The same package is used to install add-ins for Yandex.Browser, Microsoft Edge, and Chromium-Gost.

Add-ins for Safari
Creating an adapter for Safari
The Safari add-in adapter is an NPAPI plugin. The NPAPI plugin registers one or more supported MIME media types in the browser. When
creating a new add-in, the developer must select a MIME media type to be used
as its UUID. We recommend that you begin the MIME media type name with
application/ and include the add-in version number in it. For example,
application/my-component-1. When selecting a MIME media type, make sure that
there are no conflicts with the registered
MIME media type. If a new add-in version is
released, update the version number in the MIME media type. Otherwise, the web
client will continue using the old add-in version.
Let us assume that the configuration uses an add-in whose
MIME media type is application/my-component-3. The developer releases a new
add-in version. To include it in the configuration, rebuild the adapters for
Safari by changing the MIME media type in them to application/my-component-4.
Then rebuild distribution packages and include them in the 
archive to import
to the configuration. Also, change the
archive manifest file by changing the MIME media type in it to
application/my-component-4. After that, import the archive to the
configuration. What happens when you start the web client with a new
configuration on the device where the previous add-in version is installed? The
web client receives the following add-in MIME media type from the
configuration: application/my-component-4. This MIME media type is not
registered in the browser, so the old add-in version will not be used. To use
the add-in, the user must install it. However, the old version is not deleted.
It remains available for use with earlier configurations.

The developer can create an extension based on the AddInNPAPI project from
the example directory. In the AddInNPAPI.cpp file, change the values of the
nameFilePrj, nameFileComponent, and mimeType variables. nameFilePrj must
contain the adapter file name (for example, AddInNPAPI.dyn), nameFileComponent
must contain the add-in file name (for example, AddInNative.dyn). mimeType
contains the add-in MIME media type.
The adapter for Safari on Mac OS X is already built and
supplied in the lib folder: 1CEAdnWebNPAPISafOSX.bundle. An add-in for Mac OS
also needs to be built as a bundle. We recommend that you build a 32/64-bit
Universal module that contains at least the i386 and x86_64 architectures. The
example/NativeAPI/MacBuild folder contains the XCode project that builds an
add-in example for Mac OS.
Creating a distribution package for
Safari
To create a package for Mac OS X, use the PackageMaker
application in PKG format. The package must be signed with the developer's
digital signature (unless the add-in is to be installed on Mac OS X 10.4 Tiger
and earlier).
To create a package, follow these steps:
1. Copy 1CEAdnWebNPAPISafOSX.bundle from the lib folder
to another folder. Rename the file, but keep the .bundle extension.
2. Find the Info.plist file in the bundle content and
open it for editing. In the file, change the MIME media type to the one used
for your add-in. Also, change the extension description and other parameters.
3. In the Contents folder, create a PlugIns folder. Copy
the bundle of the add-in built for Mac OS into this folder. Install the
resulting adapter bundle with the add-in in the /Library/Internet Plug-Ins
folder.
4. Build the distribution package. To do it, use the
PackageMaker utility included in XCode. When installing, the package must only
copy the bundle to the /Library/Internet Plug-Ins folder.
Preparing
add-ins for import into a configuration
You can pack add-ins into a ZIP archive. It is required
for operations in the thin client, web client, and mobile platform.
1C:Enterprise for PC must include:
    
 
  • 
	Add-ins for Windows (x86, x86_64),
     GNU/Linux (x86, x86_64, ARM64, E2K), and MacOS (x86_64). 
    • 
 
  • 
	Extensions created for Internet
     Explorer (x86, x86_64), Mozilla Firefox, and Google Chrome (Microsoft
     Windows x86 and x86_64, GNU/Linux x86, x86_64, ARM64, E2K, MacOS x86_64).
1C:Enterprise for the mobile platform must include
add-ins for Microsoft Windows Runtime (x86, x86_64, ARM),
Android (x86, x86_64, ARM, ARM64, and the *.apk file – optional for
Java code), and iOS (ARM and ARM64 merged into a universal file). iOS
requires both dynamic and static libraries. The archive contains the
MANIFEST.XML file and its description. For the mobile 1C:Enterprise platform,
the archive can also include the following optional files:
    
 
  • 
	IOS_MANIFEST_EXTENSIONS.XML for iOS describes permissions for using additional subsystems (framework) if they are required. 
  • 
	ANDROID_MANIFEST_EXTENSIONS.XML for Android describes changes in AndroidManifest.xml if they are required. 
  • 
	WINDOWS_RT_MANIFEST_EXTENSIONS.XML for Windows Runtime describes changes in AppxManifest.xml if they are required. 
In 1C:Enterprise for PC, add-in archives are imported to configuration templates of the "Add-in" or "Binary data" type.
In the mobile 1C:Enterprise platform, add-in archives are imported to configuration templates of the "Add-in" type.
MANIFEST.XML file description
Copy to clipboard
<?xml
version="1.0" encoding="UTF-8" ?>

<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle"
name="YouComponentName">

<component os="Windows" path="AddIn_ChrWindows_x86.exe"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="i386" client="Firefox" clientVersion="40.*"
/>

<component os="Windows" path="AddIn_ChrWindows_x86_64.exe"
type="plugin"
object="com.YourCompanyName.YouExtensionName.1"
arch="x86_64" client="Firefox"
clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_x86.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386"
client="Firefox" clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_x86_64.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="x86_64" client="Firefox"
clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_ARM64.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="ARM64" client="Firefox"
clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="E2K" client="Firefox" clientVersion="40.*"
/>

<component os="Windows" path="Addin_IEWindows_x86.exe"
type="plugin" object="MyComponentIE.AddInServiceEx"
arch="i386" client="MSIE" />

<component os="Windows" path="AddIn_IEWindows_x86_64.exe"
type="plugin" object="MyComponentIE.AddInServiceEx"
arch="x86_64" client="MSIE" />

<component os="Windows"
path="AddIn_ChrWindows_x86.exe"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="i386" client="Chrome" />

<component os="Windows"
path="AddIn_ChrWindows_x86_64.exe"
type="plugin"
object="com.YourCompanyName.YouExtensionName.1"
arch="x86_64" client="Chrome" />

<component os="Linux"
path="AddIn_ChrLinux_x86.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="i386"
client="Chrome" />

<component os="Linux"
path="AddIn_ChrLinux_x86_64.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="x86_64"
client="Chrome" />

<component os="Linux"
path="AddIn_ChrLinux_ARM64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="ARM64" client="Chrome" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="E2K" client="Chrome" />

<component os="MacOS"
path="AddIn_ChrMacOS_x86_64.pkg" type="plugin"
object="com.YourCompanyName.YouExtensionName.1"
arch="x86_64" client="Chrome" />

<component os="Windows"
path="AddIn_ChrWindows_x86.exe"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="i386" client="AnyChromiumBased" />

<component os="Windows"
path="AddIn_ChrWindows_x86_64.exe"
type="plugin"
object="com.YourCompanyName.YouExtensionName.1"
arch="x86_64" client="AnyChromiumBased" />

<component os="Linux"
path="AddIn_ChrLinux_x86.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="i386"
client="AnyChromiumBased" />

<component os="Linux"
path="AddIn_ChrLinux_x86_64.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="x86_64"
client="AnyChromiumBased" />

<component os="Linux"
path="AddIn_ChrLinux_ARM64.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="ARM64"
client="AnyChromiumBased" />

<component os="MacOS"
path="AddIn_ChrMacOS_x86_64.pkg" type="plugin"
object="com.YourCompanyName.YouExtensionName.1"
arch="x86_64" client="AnyChromiumBased" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh"
type="plugin" object="com.YourCompanyName.YouAddInName.1"
arch="E2K" client="AnyChromiumBased" />

<component os="Windows" path="AddInNative_Win32.dll"
type="native" arch="i386" />

<component os="Windows" path="AddInNative_Win64.dll"
type="native" arch="x86_64" />

<component os="Linux" path="AddInNative_Lin32.so"
type="native" arch="i386" />

<component os="Linux" path="AddInNative_Lin64.so"
type="native" arch="x86_64" />

<component os="Linux" path="AddInNative_LinARM64.so"
type="native" arch="ARM64" />

<component os="Linux" path="AddInNative_LinE2KV4-8C.so"
type="native" arch="E2K" />

<component os="MacOS" path="AddInNative_MacOS64.dylib"
type="native" arch="x86_64" />

<component os="iOS" path="AddInNative_iOS.dylib"
type="native" arch="Universal"
buildType="developer" />

<component os="iOS" path="AddInNative_iOS.a"
type="native" arch="Universal"
buildType="release" />

<component os="Android" path="libAddInNative_Android_i386.so"
type="native" arch="i386" codeType="c++" />

<component os="Android" path="AddInNative_Android.apk"
type="native" arch="i386" codeType="java" />

<component os="Android" path="libAddInNative_Android_x64.so"
type="native" arch="x86_64" codeType="c++" />

<component os="Android" path="AddInNative_Android.apk"
type="native" arch="x86_64" codeType="java" />

<component os="Android" path="libAddInNative_Android_ARM.so"
type="native" arch="ARM" codeType="c++" />

<component os="Android" path="AddInNative_Android.apk"
type="native" arch="ARM" codeType="java" />

<component os="Android" path="libAddInNative_Android_ARM64.so"
type="native" arch="ARM64" codeType="c++" />

<component os="Android" path="AddInNative_Android.apk"
type="native" arch="ARM64" codeType="java" />

<component os="WindowsRuntime" path="AddInNative_WinRT_ARM.dll"
type="native" arch="ARM" />

<component os="WindowsRuntime" path="AddInNative_WinRT_x64.dll"
type="native" arch="x86_64" />

<component os="WindowsRuntime" path="AddInNative_WinRT_Win32.dll"
type="native" arch="i386" />

</bundle>,
Where:
    
 
  • 
	Name. Add-in name (required only
     for the mobile platform). It must be unique and generated according to the
     rules described in the "Add-in naming rules" section. 
    • 
 
  • 
	Os. Operating system (Windows,
     Linux, MacOS, WindowsRuntime, Android, or iOS). 
    • 
 
  • 
	Path. File name in the archive. 
    • 
 
  • 
	Type. Add-in type: plugin (browser
     extension), native (Native add-in), or com (COM add-in). For the mobile
     platform add-in, only the "native" value is available. 
    • 
 
  • 
	Object. Name of the object to be
     created by the browser. 
    • 
 
  • 
	Arch. Processor architecture for
     which the add-in will be used: 
    • 
 
      
  
    • 
	i386: 32-bit processor. 
      • 
  
    • 
	x86_64: 64-bit processor. 
      • 
  
    • 
	ARM: 32-bit processor with ARM
      architecture. 
      • 
  
    • 
	ARM64: 64-bit processor with ARM
      architecture. 
      • 
  
    • 
	E2K: 64-bit processor with
      Elbrus-8C architecture.
    • 
	Universal: universal binary file
      for iOS that contains an executable code for ARM and ARM64 
      • 
 
    
 
  • 
	Client: used for the web client.
     It specifies the browser the add-in is used for: MSIE (Internet Explorer),
     Firefox (Mozilla Firefox), YandexBrowser (Yandex.Browser), Edge (Microsoft
     Edge), Chrome (Google Chrome), ChromiumGost (Chromium-Gost), or
     AnyChromiumBased (all browsers based on Chromium source texts). For
     compatibility with earlier platform versions, it is recommended that you
     add a separate record for Chrome. 
    • 
 
  • 
	clientVersion: browser version. It
     is required for Mozilla Firefox. 
    • 
 
  • 
	buildType. Target application
     type: developer (the application that imports the file is for developers),
     release (for the published application version). The parameter is applied
     to iOS. 
    • 
 
  • 
	codeType. Library programming
     language: c++ (the library is written in c++), java (the library is
     written using Java Native Interface). The parameter is applied to Android.
     
    • 




Compliance of clientVersion versions specified in the
manifest and Mozilla Firefox browser versions:
Manifest.xmlFirefox
40.*40 or later
If you change add-ins (new release, bug fixing, and
other), add the new version to the file name. For example: AddInNative_1_1.so.
This rule is not applied to browser extensions. For them, change the
"object" name.
Note that records for Google Chrome and Mozilla Firefox
refer to the same distribution package.
IOS_MANIFEST_EXTENSIONS.XML file
description
The IOS_MANIFEST_EXTENSIONS.XML file is used by the
builder only for iOS. The file is optional. The file is used to make additional
changes to the mobile application:
    
 
  • 
	Enable subsystems (framework)
     required for the add-in for the application being built. 
    • 
 
  • 
	Include additional key/value pairs
     in Info.plist. 
    • 




Consider the following example:
Copy to clipboard


<?xml version="1.0" encoding="UTF-8"?>
<root>

	<!-- Секция подключения framework-ов -->
	<Additions>
        
		<framework name="System/Library/Frameworks/CoreMotion.framework"/>
		<framework name="usr/lib/libgll.dylib"/>
		
	</Additions>

	<!-- Секция добавления значений в Info.plist -->
	<Info_plist>
		<key>CFLanguage</key>
		<dict>
			<key>CFListLanguage</key>
			<array>
				<string>en</string>
				<string>ru</string>
				<string>fr</string>
			</array>
		</dict>
	</Info_plist>
</root>
The standard XML header is followed by the <root>
tag.
You can only add information to the <Additions> and
<Info_plist> tags. Tags can be in any order.
The <framework> tags in the name="…"
attribute specify the full path and subsystem name to the builder.
All content of the <Info_plist> tag(s) is added to
the <dict></dict> root tag of the Info.plist file by the builder
without any analysis or changes.
ANDROID_MANIFEST_EXTENSIONS.XML file
description
The ANDROID_MANIFEST_EXTENSIONS.XML file is used by the
builder for Android only. The file is used to make changes to the
AndroidManifest.xml manifest. For example, adding required add-in rights to
certain add-ins or application functionality. The file is optional. If the file
is missing, the builder interprets it as no additional changes in
AndroidManifest.xml.
Consider the following example:
Copy to clipboard


<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">

<!--uses-permission android:name="android.permission.WAKE_LOCK"/-->

<uses-permission android:name="%application.package%.permission.MAPS_RECEIVE"/>

<target xpath="/manifest">

	<uses-feature
	
		android:name="android.hardware.sensor.accelerometer
	
		android:required="true"/>

</target>

</root>
The standard XML header is followed by the <root>
tag with a fixed attribute. The <root> tag is similar to the
<manifest> tag in AndroidManifest.xml files.
The lines inside the <root> tag are added to the
<manifest> Android manifest tag without changes or analysis, except for
the <target> tags.
All content of the <target> tags will be inserted
into the part of AndroidManifest.xml specified in the xpath="…"
attribute.
You can localize the effect of lines on specific packages
by specifying "%application.package%. ...".
You can only add information to the <manifest> and
</manifest/application> tags of AndroidManifest.xml files.
The uses-permission, uses-feature, and other attributes
are described in the Android developer documentation.
Adding attributes with the maximum SDK version to the
uses-permission tags is not recommended. This can lead to conflicts when
building applications with multiple add-ins.
WINDOWS_RT_MANIFEST_EXTENSIONS.XML file
description
The WINDOWS_RT_MANIFEST_EXTENSIONS.XML file is used by
the builder for Windows Runtime. The file is used to make changes to the
AppxManifest.xml manifest. For example, adding required add-in rights to
certain add-ins or application functionality. The file is optional. If the file
is missing, the builder interprets it as no additional changes in permission
settings.
Consider the following example:
Copy to clipboard


<?xml version="1.0" encoding="UTF-8"?>
<root>

<Additions>

  	<target xpath="/Package/Capabilities/Capability[@Name='musicLibrary']"/>

  	<target xpath="/Package/Capabilities/DeviceCapability[@Name='proximity']"/>

</Additions>

</root>
The standard XML header is followed by the <root>
tag.
You can only add information to the <Additions>
tag.
The <target> tags in the xpath="…"
attribute specify the path of the "Name='XXXXX'" parameters in the
AppxManifest.xml file to the builder.
The <Capability> and <DeviceCapability> tags
are described in the Windows developer documentation.

Add-in naming rules for the mobile 1C:Enterprise platform
Since you can use multiple add-ins by different
developers in the mobile application, add-in names might cause conflicts. To
avoid them, follow the add-in naming rules mentioned below.
The add-in name must consist of Latin letters and/or
digits and cannot include spaces. You can also use an underscore (_). The first
character can be either a letter or an underscore (_). The add-in name is
case-sensitive.
If the application is created in a company that has its
own website and the website domain name is, for example, 1c.com, the add-in
name must begin with the same words written in reverse order: com_1c. Dots are
replaced with underscores (_). The underscore (_) is followed by the add-in
name.
If the website name conflicts with the add-in name
requirements, you can take the following steps: 



    
 
  • 
	If the name contains a prohibited
     character, for example, a dash, it can be replaced with an underscore. 
    • 
 
  • 
	If the name matches a keyword, you
     can add an underscore at the end. 
    • 
 
  • 
	If the name starts with a digit,
     you can add an underscore before it. 
    • 




Add-in
restrictions
The developer must consider that add-ins can be attached
both in window applications (thin client, thick client) and console
applications (for example, 1C:Enterprise server or web client). The main
window, window system, message queue, and timers using the message queue may be
missing in console applications, as well as the possibility to add a local hook
(for example, to the keyboard) In this case, the add-in developer must create
the necessary environment manually for the add-in to function correctly.
If you use the add-in technology in the mobile platform,
the following methods cannot be called:
    
 
  • 
	bool ADDIN_API Confirm(const
     WCHAR_T* queryText, tVariant* retVal) 
    • 
 
  • 
	bool ADDIN_API Alert(const
     WCHAR_T* text) 
    • 




from the system stream, as displaying modal windows in
this case might cause the application to hang.
Windows Runtime does not support import of dynamic
libraries from a web publication.
This option is supported on iOS 9.3.5 or earlier.
Description of examples
This distribution package includes implementation
examples for add-ins developed using Native API and COM, as well as extensions
for Mozilla Firefox, Google Chrome, and Internet Explorer. The distribution package
also contains a template to simplify add-in creation "from scratch".
The provided add-in implementations are very similar to
each other (same IDs, names, and so on), which makes them easier to analyze and
understand.
The mobile platform example is different from the others
due to its specific features. The example demonstrates implementation of a
simplified pedometer. You can find it in the \example\NativeAPIMobile\
directory.
To fully build examples for personal computers, the
developer needs 
CMake 3.6 or later. To build installers for Windows, the developer needs 
NSIS. To build installers for GNU/Linux, the developer needs 
makeself.
Add-ins implement the following properties and methods:

Examples of 1C:Enterprise add-in for personal computers
Properties
IsEnabled
Use: Read and write.
Description: Type: Boolean. Contains an add-in state.
IsTimerPresent
Use: Read.
Description: Type: Boolean. Identifies whether an add-in has a timer.
Methods
Enable
Syntax:
Copy to clipboard
Enable()
Description:
Enables the add-in object.
Disable
Syntax:
Copy to clipboard
Disable()
Description:
Disables the add-in object.
ShowInStatusLinee
Syntax:
Copy to clipboard
ShowInStatusLine (<Text>)
Parameters: 
    
 
  • 
	Text. Text displayed in the status line. 
Description:
Displays a received text in the status line for 5 seconds.
StartTimer
Syntax:
Copy to clipboard
StartTimer()
Description:
Starts add-in timer. Every second, the add-in sends a message with the Component and Timer parameters and a system clock counter string to 1C:Enterprise.
StopTimer
Syntax:
Copy to clipboard
StopTimer()
Description:
Stops add-in timer.
Besides, the add-in developed using Native API implements an additional method.
LoadPicture
Syntax:
Copy to clipboard
LoadPicture(<FileName>)
Parameters: 
    
 
  • 
	FileName. Name of a file with an image. 
Description:
Imports an image from the specified file and passes it to 1C:Enterprise.
ShowMessage 
Syntax:
Copy to clipboard
ShowMessage()
Parameters: 
None
Description:
Displays a message about the platform version.
Add-in example for the mobile 1C:Enterprise platform
Properties
IsEnabled
Use: Read.
Description: Type: Boolean. Contains an add-in state.
Methods
Enable
Syntax:
Copy to clipboard
Enable()
Description:
Enables the add-in object. That triggers the pedometer countdown and tracking of the movement type with accelerometers.
The add-in generates an event with the "StepCounter", "OnChange", and "_" parameters for 1C:Enterprise when the number of steps changes.
Disable
Syntax:
Copy to clipboard
Disable()
Description:
Disables the add-in object. That resets the number of steps to zero and stops tracking of movement type values with accelerometers.
GetStepCount
Syntax:
Copy to clipboard
GetStepCount()
Type:
Integer value.
Description: 
Returns the current calculated value of the operator steps starting from the latest Enable() method call.
GetMovementType
Syntax:
Copy to clipboard
GetMovementType()
Type:
Integer value.
Description: 
Returns the current movement type index.
0: undefined
1: still
2: walking
3: running
4: driving
5: riding a bicycle
GetDeviceOrientation
Syntax:
Copy to clipboard
GetDeviceOrientation(<Plane>)
Parameters:
Plane. Cartesian coordinate system plane of requested data (0 is plane XOY, 1 is plane XOZ, 2 is plane YOZ).
Type:
Real value.
Description: 
Returns current values of device orientation by Cartesian planes, in radians.
ShowDeviceOrientation
Syntax:
Copy to clipboard
ShowDeviceOrientation()
Description:
Displays a message about current values of device orientation by Cartesian planes, in radians.
GetDescriptionLastError
Syntax:
Copy to clipboard
GetDescriptionLastError()
Description:
Returns the text of the last add-in error.
Events
ExternEventProcessing
Syntax:
Copy to clipboard
Procedure ExternEventProcessing (Source, Event, Data)

	If Source = "StepCounter" And Event = "OnChange" Then

		. . .

	EndIf

EndProcedure

Note: <Data> for the specified example is "_".
Description: 
Appears when an add-in sends a message about a change in the number of steps.
 



Development tools
You can use the following development tools:
    
 
  • 
	Microsoft Visual C++ 
  • 
	Delphi 
  • 
	C++ Builder 
  • 
	Xcode 
  • 
	Eclipse 
  • 
	gcc 
  • 
	CMake