Add-in development technology

- Introduction
- Delivery kit directory structure
- Creating add-ins with Native API technology
  - Add-in interface
  - Localization
  - 1C:Enterprise interface
  - Mapping between tVariant and 1C:Enterprise types
  - Specifics of add-in development using Native API
    - Publishing settings for 1C:Enterprise mobile platform
    - Windows Runtime
    - Android
    - iOS
    - Signing add-ins with developer certificates
    - Static library
- Creating add-ins with COM technology
  - Initializing and unloading add-ins
  - 1C:Enterprise script extension
  - Localization
  - Using COM VARIANT type in data exchange
    - Calling add-in functions
    - Returning values from add-ins
    - Calling 1C:Enterprise object methods from add-ins
  - COM interfaces of 1C:Enterprise
    - Saving add-in object parameters
    - Notification messages about object states
    - Dialog boxes
    - Getting platform info
    - External events
    - Status bar operations
  - Creating windows in 1C:Enterprise environment
  - Accessing 1C:Enterprise methods and properties using OLE automation
  - Methods and properties available through OLE Automation
  - Specifics of add-in development using COM
- Preparing add-ins for working with the web client
  - Add-ins for Microsoft Internet Explorer
    - Creating adapters for Microsoft Internet Explorer
    - Creating installer packages for Microsoft Internet Explorer
  - Add-ins for Google Chrome and Mozilla Firefox
    - Creating adapters for Google Chrome and Mozilla Firefox
    - Creating installer packages for Google Chrome and Mozilla Firefox
  - Add-ins for Safari
    - Creating adapters for Safari
    - Creating installer packages for Safari
- Preparing add-ins for loading them to configurations
  - MANIFEST.XML file description
  - IOS_MANIFEST_EXTENTIONS.XML file description
  - ANDROID_MANIFEST_EXTENTIONS.XML file description
  - WINDOWS_RT_MANIFEST_EXTENTIONS.XML and WINDOWS_RT_PHONE_MANIFEST_EXTENTIONS.XML file descriptions
  - 1C:Enterprise add-in naming rules
  - Add-in limitations
- Example descriptions
  - 1C:Enterprise add-in examples for desktop computer
  - 1C:Enterprise add-in example for mobile platform
  - Development tools

# Introduction

The 1C:Enterprise software system is designed to perform a wide range of business automation tasks. It includes powerful tools for configuring off-the-shelf applications to match business processes of a specific company. At the same time, 1C:Enterprise is an open system. You can use the built-in import and export tools, which support plain text and XML formats, for communication with other software systems. The platform supports the OLE Automation software integration standard and provides web service access. However, a closer interaction between 1C:Enterprise and other software systems may be required to solve specific integration tasks.

The add-in technology is provided for solving such tasks. This technology is used to develop programs that dynamically attach to 1C:Enterprise and then closely interact with it. Add-ins provide solutions for a wide range of tasks, including integration with point-of-sale equipment. Add-ins can be attached to 1C:Enterprise application servers, as well as to the client applications, including the web client.

The delivery kit includes this manual and a set of add-in implementation examples.

The manual describes creation of add-ins based on Native API and COM.

# Delivery kit directory structure

The doc directory contains this document.

The example directory contains examples of add-ins based on COM and Native API. This directory also contains examples of web browser add-ins and mobile platform add-ins.

The include directory contains a set of header files that you can include in your add-in project.

The lib directory contains static libraries required for add-in development for Mozilla Firefox, Google Chrome, Safari, and Internet Explorer web browsers.

The template directory contains a template for add-in development based on the Native API technology.

The templateMobile directory contains a template for mobile platform add-in development based on the Native API technology

# Creating add-ins with Native API technology

Use this technology to create add-ins that can be attached to client applications and 1C:Enterprise servers on Windows, Linux, Windows Runtime, Android, and iOS platform versions.

The user interface is not available for Windows Runtine, Android, and iOS.

An add-in implements one or several objects availlable for use from 1C:Enterprise. Each add-in object must inherit the IComponentBase abstract class and implement all of its methods. The ComponentBase.h file is included in the distribution kit.

An add-in developed using this technology must export the following four functions from the library:

GetClassNames

Description:

Gets the list of add-in object names.

Syntax:

const WCHAR_T* GetClassNames();

Return value:

An array with a list of add-in object names.

GetClassObject

Description:

Creates an instance of the add-in object.

Syntax:

long GetClassObject(const WCHAR_T* clsName, IComponentBase** pIntf);

Parameters:

clsName

Type: const WCHAR_T*. Name of the object being created.

pIntf

Type: IComponentBase**. Pointer to the variable that will store the address of the created object.

Return value:

- 0 - the object cannot be created or the object with the specified name is not found.
- nonzero value - the object is created.

DestroyObject

Description:

Deletes an instance of a previously created object. The add-in must delete the object and release the memory using its own tools.

Syntax:

long DestroyObject(IComponentBase** pIntf);

Parameters:

pIntf

Type: IComponentBase**. Pointer to the add-in object.

Return value:

- 0 - successful completion.
- error code (Runtime error) - errors occurred.

SetPlatformCapabilities

Description:

Sets the version of supported platform capabilities. If the function is not implemented, the add-in cannot display messages and request platform information.

Syntax:

AppCapabilities SetPlatformCapabilities(const AppCapabilities capabilities);

Parameters:

capabilities

Type: AppCapabilities enumeration. Enumeration values: eAppCapabilitiesInvalid = -1, eAppCapabilities1 = 1, eAppCapabilitiesLast = eAppCapabilities1.

Return value

The version of supported platform capablities.

## Add-in interface

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

Init

Description:

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

Syntax:

bool Init(void* Interface);

Parameters:

Interface

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

Return value:

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

setMemManager

Description:

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

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

Syntax:

bool setMemManager(void* memManager);

Parameters:

memManager

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

Return value:

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

GetInfo

Description:

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

Syntax:

long GetInfo();

Return value:

The add-in version.

Done

Description:

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

Syntax:

void Done();

Return value:

None.

RegisterExtensionAs

Description:

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

Syntax:

bool RegisterExtensionAs(WCHAR_T** wsExtName);

Parameters:

wsExtName

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

Return value:

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

GetNProps

Description:

Returns the number of extension properties.

Syntax:

long GetNProps();

Return value:

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

FindProp

Description:

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

Syntax:

long FindProp(const WCHAR_T* wsPropName);

Parameters:

wsPropName

Type: const WCHAR_T*. Property name.

Return value:

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

GetPropName

Description:

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

Syntax:

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

Parameters:

lPropNum

Type: long. Sequential number of the property.

lPropAlias

Type: long. Language of the property name:

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

Return value:

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

GetPropVal

Description:

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

Syntax:

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

Parameters:

lPropNum

Type: const long. Sequential number of the property.

pvarPropVal

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

Return value:

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

SetPropVal

Description:

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

Syntax:

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

Parameters:

lPropNum

Type: const long. Sequential number of the property.

pvarPropVal

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

Return value:

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

IsPropReadable

Description:

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

Syntax:

bool IsPropReadable(const long lPropNum);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

Return value:

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

IsPropWritable

Description:

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

Syntax:

bool IsPropWritable(const long lPropNum);

Parameters:

lPropNum

Type: const long. Sequential number of the property.

Return value:

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

GetNMethods

Description:

Returns the number of methods in the extension.

Syntax:

long GetNMethods();

Return value:

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

The first method has sequential number 0.

FindMethod

Description:

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

Syntax:

long FindMethod(const WCHAR_T* wsMethodName);

Parameters:

wsMethodName

Type: const WCHAR_T*. Method name.

Return value:

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

The first method has sequential number 0.

GetMethodName

Description:

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

Syntax:

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

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

lMethodAlias

Type: const long. Language of the method name:

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

Return value:

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

GetNParams

Description:

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

Syntax:

long GetNParams(const long lMethodNum);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

Return value:

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

The first method has sequential number 0.

GetParamDefValue

Description:

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

Syntax:

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

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

lParamNum

Type: const long. Sequential number of the parameter.

pvarParamDefValue

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

Return value:

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

HasRetVal

Description:

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

Syntax:

bool HasRetVal(const long lMethodNum);

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

Return value:

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

CallAsProc

Description:

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

Syntax:

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

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

paParams

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

lSizeArray

Type: const long. Size of the paParams array.

Return value:

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

CallAsFunc

Description:

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

Syntax:

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

Parameters:

lMethodNum

Type: const long. Sequential number of the method.

pvarRetValue

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

paParams

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

lSizeArray

Type: const long. Size of the paParams array.

Return value:

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

## 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:

void SetLocale(const WCHAR_T* wsLocale);

Parameters:

wsLocale

Type: const WCHAR_T*. Locale string in the following format: <language>_<REGION>. Examples: en_US for Linux; en_US for Windows.

Return value:

None.

## 1C:Enterprise interface

During the initialization of the add-in object, the pointer to 1C:Enterprise interface is passed to it. You can use the pointer to call the methods listed in this section. Note that these methods will not work at 1C:Enterprise server side.

AddError

Description:

Adds a message that can be displayed during the execution of 1C:Enterprise script extension methods. If scode is not equal to 0, an exception is generated. You can catch and handle the exception using 1C:Enterprise script.

Possible message codes and 1C:Enterprise behavior are described in section Notification messages about object states.

Syntax:

bool AddError(unsigned short wcode, const WCHAR_T* source, const WCHAR_T* descr, long scode);

Parameters:

wcode

Type: unsigned short. Message code.

source

Type: const WCHAR_T*. Error source.

descr

Type: const WCHAR_T*. Error message.

scode

Type: long. Error code.

Return value:

- true - error details are successfully added.
- false - errors occurred.

RegisterProfileAs

Description:

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

Syntax:

bool RegisterProfileAs(WCHAR_T* wsProfileName);

Parameters:

wsProfileName

Type: WCHAR_T*. Name of the add-in parameter list.

Return value:

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

Read

Description:

Reads the add-in parameter value stored in pszPropName. If the value cannot be read and errDescriptor value is not NULL, 1C:Enterprise allocates memory and writes the error description to that memory. The add-in must release the memory by calling FreeMemory(). For return values of string type, 1C:Enterprise also allocates memory and saves the address in the corresponding field of the tVariant structure. The add-in must release that memory by calling FreeMemory().

Syntax:

bool Read(WCHAR_T* pszPropName, tVariant* pVal, long* pErrCode, WCHAR_T** errDescriptor);

Parameters:

pszPropName

Type: WCHAR_T*. Parameter name.

pVal

Type: tVariant*. Pointer to the parameter value.

pErrCode

Type: long*. Pointer to the variable that will store the error code if an error occurs.

errDescriptor

Type: WCHAR_T**. Double pointer to the variable that will store the error description.

Return value:

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

Write

Description:

Saves the add-in parameter value to pszPropName.

Syntax:

bool Write(WCHAR_T* pszPropName, tVariant* pVar);

Parameters:

pszPropName

Type: WCHAR_T*. Parameter name.

pVar

Type: tVariant*. Pointer to the parameter value.

Return value:

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

SetEventBufferDepth

Description:

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

Syntax:

bool SetEventBufferDepth(long lDepth);

Parameters:

lDepth

Type: long. Event queue size.

Return value:

- true - successful completion (the size is set).
- false - errors occurred.

GetEventBufferDepth

Description:

Returns the event queue size for the specified object.

Syntax:

long GetEventBufferDepth();

Return value:

Event queue size.

ExternalEvent

Description:

Adds the event (its source, name, and parameters) to the queue. During the event processing, that data is passed to the ExternalEventProcessing() procedure. When the ExternalEvent() method is called, further event processing is performed as follows: the event is added to the queue (if the queue is full, the event is lost), then, if no system events are available and the queue is not empty, external event processing is started for the first event in the queue. This process is repeated for all add-in objects. This synchronizes external event processing with system event processing.

Syntax:

bool ExternalEvent(WCHAR_T* wsSource, WCHAR_T* wsMessage, WCHAR_T* wsData);

Parameters:

wsSource

Type: WCHAR_T*. String that stores the event source name

wsMessage

Type: WCHAR_T*. String that stores the event name.

wsData

Type: WCHAR_T*. String that stores the event parameters.

Return value:

- true - event is added to the queue.
- false - the queue is full, event processing is not available, or an unknown error occurred.

CleanEventBuffer

Description:

Clears the event queue by deleting all events from it.

Syntax:

void CleanEventBuffer();

Return value:

None.

SetStatusLine

Description:

Sets the status bar text (displayed at the bottom part of the 1C:Enterprise window).

Syntax:

bool SetStatusLine(WCHAR_T* wsStatusLine);

Parameters:

wsStatusLine

Type: WCHAR_T*. Status bar text.

Return value:

- true - the text is displayed in the status bar.
- false - this functionality is not available, or an unknown error occurred.

ResetStatusLine

Description:

Clears the status bar.

Syntax:

void ResetStatusLine();

Return value:

None.

GetInterface

Description:

Requests the platform interface.

Syntax:

IInterface* GetInterface(Interfaces iface)

Parameters:

iface

Type: Interfaces. The value of the Interfaces enumeration: eIMsgBox or eIPlatformInfo.

Return value:

- IInterface* - pointer to the requested interface.
- 0 - the requested interface is not supported by the platform.

Confirm

Description:

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

Syntax:

bool Confirm(const WCHAR_T* queryText, tVariant* retVal)

Parameters:

queryText

Type: WCHAR_T*. Question text.

retVal

Type: tVariant*. Return value of the dialog box, which has VTYPE_BOOL type: true for clicking OK, or false for clicking Cancel.

Return value:

- true - the dialog box is displayed.
- false - the dialog box is not displayed.

Alert

Description:

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

Syntax:

bool Alert(const WCHAR_T* text)

Parameters:

text

Type: WCHAR_T*. Message text.

Return value:

- true - the dialog box is displayed.
- false - the dialog box is not displayed.

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:

AppInfo* GetPlatformInfo()

Return value:

- AppInfo* - pointer to a structure with the following fields:
  - AppVersion. Type: WCHAR_T*, application version.
  - Application. Type: enumeration, type of application that attached the add-in.
  - UserAgentInformation. Type: WCHAR_T*, browser info (for the web client only).

## Mapping between tVariant and 1C:Enterprise types

1C:Enterprise and COM types are mapped as follows:

- Values of VTYPE_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 VTYPE_I2, VTYPE_I4, VTYPE_ERROR, and VTYPE_UI1 types are mapped to integer values, they are stored in lVal.
- Values of VTYPE_BOOL type are mapped to boolean values, they are stored in bVal.
- Values of VTYPE_R4, VTYPE_R8, and VTYPE_CY types are mapped to noninteger values, they are stored in dblVal.
- Values of VTYPE_DATE type are mapped to date values, they are stored in date.
- Values of VTYPE_TM type are mapped to date values, they are stored in struct tm tmVal.
- Values of VTYPE_PSTR type are mapped to string char* values, they are stored in pstrVal with length specified in strLen.
- Values of VTYPE_PWSTR type are mapped to string WCHAR_T* values, they are stored in pwstrVal with length specified in wstrLen.
- Values of VTYPE_BLOB type are mapped to binary data, they are stored in pstrVal with length specified in strLen.

Warning! VTYPE_INTERFACE and VTYPE_VARIANT types are not supported.

Note. Numeric values passed as parameters from a web client can have any numeric types.

The VTYPE_BLOB type is not supported in the web client.

## Specifics of add-in development using Native API

Add-ins developed using this technology are platform-dependent. Therefore, you have to build add-in versions for both x86 and x86-64 platforms. Configuration developers are responsible for defining the platform type and loading the appropriate add-in versions.

An add-in can be loaded to a 1C:Enterprise application server that is running on any of the available operating systems, so we recommend that you create a cross-platform implementation.

1C:Enterprise supports Unicode (WCHAR_T) string format with 2 bytes per character. This length is equal to that of wchar_t type on Windows. However, it might be different on other operating systems where the wchar_t size can be 4 bytes. This is why you have to implement the conversion for character data of this type.

If an add-in uses additional modules, describe them in the add-in documentation. We recommend that you statically include required nonsystem runtime libraries in your add-in (provided that the library licenses permit this option) because they might not be available on the end-user computer, or an end user might have different versions of these libraries installed. Also, include a manifest file in Windows add-in versions.

Ensure that each exception is caught and processed in your add-in, and then the exception info is passed to 1C:Enterprise using the AddError() method.

If an add-in is running on a 1C:Enterprise server, external events are not processed. Also, methods that manage the status bar or save any parameters are not processed.

An add-in can return any binary data, for example, a generated barcode image. For that purpose, store data in the pstrVal field of the tVariant structure, store data length in the strLen field, and set data type to VTYPE_BLOB. 1C:Enterprise uses the BinaryData type for this data type.

Pass date values to your add-in as tm structures with VTYPE_TM type. The add-in can return date values both as struct tm or as Windows DATE values with VTYPE_DATE type (1C:Enterprise will process it correctly).

Warning! Return values of VTYPE_ARRAY and VTYPE_BYREF types are not suported.

### Publishing settings for 1C:Enterprise mobile platform

Before the publishing, in the HTTP server settings, add MIME types for the following extensions:

- .so
- .apk
- .dylib
- .a

MIME type: application/octet-stream

#### Windows Runtime

Add-in development for Windows Runtime and Windows Runtime Phone requires Windows version 8.1 with MS Visual Studio 2013 SP4 (Windows Phone SDK archive).

The add-in development result is a set of dynamic libraries (*.dll) for smartphones and tablets with all supported CPU architectures.

See the add-in project examples in directory \example\NativeAPIMobile\WinRT_Proj\.

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

- Store. MS Visual Studio project for tablets.
- Phone. MS Visual Studio project for smartphones.

Before debugging, extract 1cem-XXXXX.appx or 1cem-phone-XXXXX.appx archive content to the appx\ directory.

Then, after you add the add-in source code, you can use standard MS Visual Studio debug tools.

For Windows Runtime and Windows Runtime Phone, the option to load dynamic libraries from published applications is not implemented.

#### Android

To develop add-ins for Android, you can use either C++ or Java Native Interface.

The add-in development result is a set of dynamic libraries (*.so) for all supported CPU architectures. If you use Java code, the result must also include an .apk file. The .apk file is not a standalone application, it is not intended for running on its own. It is included in the mobile application package.

See the project example in directory \example\NativeAPIMobile\Android_Proj\.

To debug an add-in, you can also use the option to load dynamic libraries from web publications. The libraries are loaded automatically after you update a configuration (with those libraries included) on a mobile device from a web publication on a developer computer.

#### iOS

iOS developers cannot use nonsystem dynamic libraries in applications that are published to AppStore. Therefore, you can use such libraries for development and debug purposes only.

The add-in development result is a dynamic library file *.dylib signed with a developer certificate (for testing purposes) and a binary static linking file *.a (for the application builder).

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

Then, after you add the add-in source code, you can use standard Xcode debug tools.

To debug an add-in, you can also use the option to load dynamic libraries from web publications. The libraries are loaded automatically after you update a configuration (with those libraries included) on a mobile device from a web publication on a developer computer.

#### Signing add-ins with developer certificates

You can sign an add-in with a developer certificate using the codesign utility. Use the following syntax:

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

Example:

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

#### Static library

The static library *.a is intended for building the application by linking an add-in to the platform.

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

The static component registration is performed during the application startup. See the following example.

#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

See the project example in directory \example\NativeAPIMobile\iOS_Proj\

# 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.

# Preparing add-ins for working with the web client

Add-ins interact with the web client using extensions. Projects for creating Mozilla Firefox, Google Chrome, Internet Explorer, and Safari extensions are provided in the examples. For security reasons, each extension can work with a single add-in specified at the compilation stage. Each extension consists of an add-in (possibly created using the COM technology) and a browser adapter.

For Microsoft Windows and Mac OS X operating systems, all executable files included in the installer package and the installer package itself must be signed with the developer's digital signature. For Microsoft Windows installer packages, dual signing (SHA-1 and SHA-256) is required, with the exception of MSI packages (see the Microsoft recommendation).

The browser script language is single-threaded. Therefore, you have to avoid callbacks from secondary add-in threads. Only the following methods will work in secondary threads: ExternalEvent(), SetStatusLine(), and ResetStatusLine().

Libraries of Windows browsers use the Visual Studio 2013 compiler.

On platform versions 8.3.6 and later, Firefox and Google Chrome use the same adapter.

## Add-ins for Microsoft Internet Explorer

### Creating adapters for Microsoft Internet Explorer

Use the AddInIE project from the example directory as a basis for the extension development. In the IDL file, change the library name (for example, MyAddInIELib library), coclass UUIDs, and library UUIDs. All places that require changes are marked with the //change comment. Do not change the interface names and UUIDs. We recommend that you rename the project (for example, to MyAddInIE). In the config.cpp file, change the AddInIE_i.h header file name to the name generated by the IDE based on the data from the IDL file and change the text variable values to the library coclass names (for example, to MyAddInIE.AddInServiceEx). Set the LIBID_AddInWebLib variable to the LIBID of your library. In the nameFileComponent variable, specify the add-in name (for example, AddInNative.dll). In the nameFilePrj variable, specify the target file name of the project (for example, MyAddInIE.dll). Since the extension for Microsoft Internet Explorer is a COM object, take into account the content of the Specifics of add-in development using COM section.

### Creating installer packages for Microsoft Internet Explorer

The installer package for Internet Explorer is a CAB archive. To build the archive, download MS CAB SDK. The example\PackageIE folder contains the example of the installation package building. Change the name of the addin.inf file to match your add-in name (for example, MyAddIn.inf). Include the following information related to your add-in project in the file:

- File and directory names.
- In the LayoutFile property and in the inffile section, specify the name of the INF file.

Provide options for correct deletion of the add-in installed in Internet Explorer using the Add/Remove Programs operating system component.

Since version 8.2.11, 1C:Enterprise is capable of determining the add-in installation result. If the add-in will be used with earlier 1C:Enterprise versions, the developer must provide the method to inform the user whether the add-in is installed correctly.

For more information about the INF file format, see http://msdn.microsoft.com/en-us/library/aa376858(VS.85).aspx. The script for building the CAB file is available in buildcab.bat.

## Add-ins for Google Chrome and Mozilla Firefox

### Creating adapters for Google Chrome and Mozilla Firefox

The add-in adapter for Chrome and Firefox is a console application. During the installation it registers one or several unique extension types. We recommend that you begin extension names with "com." and include the add-in version numbers in them (for example, com.YourCompanyName.YourAddInName.1). When you release a new add-in version, increment the version number in its name, otherwise the web client will use the old version of the add-in.

For example, an add-in with name com.YourCompanyName.YourAddInName.3 is used in a configuration. When you release a new add-in version, to include it in the configuration, rebuild the Chrome adapter with name changed to com.YourCompanyName.YourAddInName.4. Then rebuild the installation packages and include them in the archive that will be loaded to the configuration. Also, in the archive manifest file, change the name to com.YourCompanyName.YourAddInName.4. Then load the archive to the configuration. When the web client is started with the new configuration on the computer where the previous add-in version is installed, the web client retrieves the name com.YourCompanyName.YourAddInName.4 from the configuration. Since this name is not registered in the browser, the previous add-in version will not be used. To start using the new add-in version, the user must install it. The previous add-in version remains installed and can be used with earlier configuration versions.

Use the AddInChrome project from the example directory as a basis for add-in development. In the config.cpp file, change the values of the following variables: nameFilePrj and nameFileComponent. The nameFilePrj variable contains the adapter file name (for example, AddInChrWin32.exe). The nameFileComponent variable contains the add-in file name (for example, AddInNative.dll).

The adapters are based on the jsoncpp library (view license).

### Creating installer packages for Google Chrome and Mozilla Firefox

The Windows version of the installer package for Google Chrome has the EXE format.

The installation package must include:

- Add-in file
- Add-in adapter file
- Manifest file (in JSON format)

Use the following manifest file template:

    {
    "name": "com.YourCompanyName.YourAddInName",
    "description": "Description of add-in for Chrome and Firefox",
    "path": "AddInChr.exe",
    "type": "stdio",
    "allowed_origins": [
    "chrome-extension://pbhelknnhilelbnhfpcjlcabhmfangik/"
    ]
    }

Change the following template sections:

Section | Description
--- | ---
name | Add-in name
description | Displayed add-in description
path | Full path to the add-in adapter file

Do not change the rest of the attributes.

During the installation, the package must copy the files to the hard disk and register the add-in as a browser plug-in in the following system register branch: HKCU\Software\Google\Chrome\NativeMessagingHosts\com.YourCompanyName.com.YourAddInName (replace YourCompanyName and YourAddInName with the actual values). In this branch, create a single parameter with default String type that stores the full path to the manifest file. The value in the name section of the manifest file must match the register branch name.

The package must be signed with the digital signature of the developer (SHA1 + SHA256).

The example\AddInChromeSetup directory contains a NSIS project for building the installer package for the add-in example. You will need NSIS for compiling the project. For each add-in, set a unique value in the AddInChromeSetup.nsh file.

The Linux version of the Chrome and Firefox installer package is provided as a self-extracting archive, which includes binary add-in and adapter modules and the manifest file. You can use the makeself utility to create the archive. The archive script must copy the manifest to the ~/.config/google-chrome/NativeMessagingHosts/ directory and copy the executable files to some other directory.

## Add-ins for Safari

### Creating adapters for Safari

The add-in adapter for Safari is a NPAPI plug-in. The NPAPI plug-in registers one or several MIME media types in the browser. During the add-in creation, the developer must select the MIME media type that will serve as a unique add-in identifier. We recommend that you start the MIME media type name from application/ and include the add-in version number in it (for example, application/myaddin-1). Ensure that the MIME media type that you use does not conflict with any of the registered MIME media types. When you release a new add-in version, increment the MIME media type version, otherwise the web client will use the old version of the add-in.

For example, an add-in with MIME media type application/my-addin-3 is used in a configuration. When you release a new add-in version, to include it in the configuration, rebuild the Safari adapter with MIME media type changed to application/my-addin-4. Then rebuild the installer packages and include them in the archive that will be loaded to the configuration. Also, in the archive manifest file, change the MIME media type to application/my-addin-4. Then load the archive to the configuration. When the web client is started with the new configuration on the computer where the previous add-in version is installed, the web client retrieves MIME media type application/my-component-4 from the configuration. Since this MIME media type is not registered in the browser, the previous add-in version will not be used. To start using the new add-in version, the user must install it. The previous add-in version remains installed and can be used with earlier configuration versions.

Use the AddInNPAPI project from the example directory as a basis for the extension development. In the AddInNPAPI.cpp file, change the values of the following variables: nameFilePrj, nameFileComponent, and mimeType. The nameFilePrj variable contains the adapter name (for example, AddInNPAPI.dyn). The nameFileComponent variable contains the add-in file name (for example, AddInNative.dyn). The mimeType variable contains the MIME media type of the add-in.

Safari adapter for MacOS X does not require building, it is already built and delivered in the lib directory (1CEAdnWebNPAPISafOSX.bundle). You have to build the add-in for Mas OS as a bundle. We recommend that you build a 32/64-bit Universal module at least for i386 and x86_64 architectures. The example/NativeAPI/MacBuild directory contains the Xcode project for building add-ins for Mac OS.

### Creating installer packages for Safari

For Mas OS X, the package is created in the PKG format using PackageMaker. The package must be signed with the developer's digital signature (unless the add-in is intended for installing on Mas OS X 10.4 Tiger or earlier Mac OS versions).

To create a package, perform the following steps:

1. Copy 1CEAdnWebNPAPISafOSX.bundle from the lib directory to another directory. Do not change the .bundle extension.
2. In the bundle content, find the file Info.plist and open it for editing. In this file, change the MIME media type to that of your add-in, and also change the add-in descriptions and other parameters.
3. In the Contents directory, create the Plugins directory. Copy the bundle of the add-in build for Mac OS to this directory. The resulting adapter bundle that includes the add-in must be installed to the /Library/Internet Plug-Ins directory.
4. Build the installation package using the PackageMaker utility available in XCode. During the installation, the package must copy the bundle to the /Library/Internet Plug-Ins directory.

# Preparing add-ins for loading them to configurations

An add-in can be packed to a ZIP archive. This is mandatory if you want to use the add-in with the thin or web client or with the mobile platform.

The archive for the desktop platform must include add-ins for Windows (x86, x86_64), GNU/Linux (x86, x86_64), extensions for Internet Explorer (x86, x86_64) and Mozilla Firefox (Windows x86, GNU/Linux x86, and x86_64).

The archive for the mobile platform must include add-ins for Windows RT (x86, ARM), Android (x86, ARM, and optional .apk file for Java code), and iOS (ARM and ARM64 combined in a single universal file). The iOS version must include both a static and a dynamic library.

The archive must also include the MANIFEST.XML file with the content description.

The archive for the mobile platform can also include the following optional files:

- IOS_MANIFEST_EXTENSIONS.XML (for iOS). Describes the permissions to use additional frameworks.
- ANDROID_MANIFEST_EXTENTIONS.XML (for Android). Describes the changes in AndroidManifest.xml.
- WINDOWS_RT_MANIFEST_EXTENTIONS.XML (for Windows Runtime). Describes the changes in AppxManifest.xml.
- WINDOWS_RT_PHONE_MANIFEST_EXTENTIONS.XML (for Windows Runtime Phone). Describes the changes in AppxManifest.xml.

In the desktop platform, add-in archives are loaded to configuration templates having "Add-in" or "Binary data" type.

In the mobile platform, add-in archives are loaded to configuration templates having "Add-in" type.

## MANIFEST.XML file description

The following is an example manifest file:

    <?xml version="1.0" encoding="UTF-8" ?>
    <bundle xmlns="http://v8.1c.ru/8.2/addin/bundle" name="YourAddInName">
    <component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
    <component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
    <component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="x86_64" client="Firefox" clientVersion="40.*" />
    <component os="Windows" path="Addin_IEWindows_x86.cab" type="plugin" object="MyAddInIE.AddInServiceEx" arch="i386" client="MSIE" />
    <component os="Windows" path="AddIn_IEWindows_x86_64.cab" type="plugin" object="MyAddInIE.AddInServiceEx" arch="x86_64" client="MSIE" />
    <component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Chrome" />
    <component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Chrome" />
    <component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="x86_64" client="Chrome" />
    <component os="MacOS" path="AddIn_SafMacOS_x86.pkg" type="plugin" object="application/add-in-example-1" arch="i386" client="Safari" />
    <component os="Windows" path="AddInNative.dll" type="native" arch="i386" />
    <component os="Windows" path="AddInNative64.dll" type="native" arch="x86_64" />
    <component os="Linux" path="AddInNative.so" type="native" arch="i386" />
    <component os="Linux" path="AddInNative64.so" 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_ARM.so" type="native" arch="ARM" codeType="c++" />
    <component os="Android" path="AddInNative_Android.apk" type="native" arch="ARM" codeType="java" />
    <component os="WindowsRuntimePhone" path="AddInNative_WinRT_Phone_ARM.dll" type="native" arch="ARM" />
    <component os="WindowsRuntimePhone" path="AddInNative_WinRT_Phone_Win32.dll" type="native" arch="i386" />
    <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 - unique add-in name (required for the mobile platform only), see 1C:Enterprise add-in naming rules
- os - operating system, one of the following:
  - Windows
  - Linux
  - MacOS
  - WindowsRuntime
  - WindowsRuntimePhone
  - Android
  - iOS
- path - file name in the archive
- type - add-in type, one of the following:
  - plugin - browser extension
  - native - native component
  - com - COM component
  For the mobile platform, the only available type is native.
- object - name of the object that will be created by the browser
- arch - CPU architecture where the add-in will run, one of the following:
  - i386 - 32-bit
  - x86_64 - 64-bit
  - ARM - 32-bit ARM
  - Universal - universal binary file for iOS containing executable code for ARM and ARM64
- client - browser used by the web client, one of the following:
  - MSIE - Internet Explorer
  - Firefox - Mozilla Firefox
  - Chrome - Google Chrome
  - Safari - Safari
- clientVersion - browser version (mandatory for Firefox)
- buildType - target application type (iOS only), one of the following:
  - developer - application build intended for developers
  - release - application to be published
- codeType - library programming language (Android only), one of the following:
  - c++ - library written in C++
  - java - library written using Java Native Interface

Correspondence between clientVersion values specified in the manifest file and Mozilla Firefox versions:

Manifest.xml | Firefox
40.* | 40 or later

When an add-in is changed (a new release or patch), add a new version number to the file name, for example: AddInNative_1_1.so. This rule does not apply to browser extensions. For extensions, change the object name.
Note that entries for Google Chrome and Mozilla Firefox refer to the same installer package.

## IOS_MANIFEST_EXTENSIONS.XML file description

The builder uses the IOS_MANIFEST_EXTENSIONS.XML file for iOS only. The file grants the builder the right to use the frameworks required by the add-in. This file is optional. If it is not available, no changes are applied to the manifest file.

The following is an example manifest extension file:

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

    <root>
        <Additions>
            <framework name="System/Library/Frameworks/CoreMotion.framework"/>

            <framework name="usr/lib/libgll.dylib"/>

        </Additions>

    </root>

The first line is a standard XML header. The second line contains the <root> tag.

You can only add data to the <Additions> tag.

The name="..." attributes of <framework> tags store framework names and paths.

## ANDROID_MANIFEST_EXTENSIONS.XML file description

The builder uses the ANDROID_MANIFEST_EXTENSIONS.XML file for Android only. This file describes the changes to AndroidManifest.xml, such as rights that an add-in requires to access specific application components or functionalities. This file is optional. If it is not available, no changes are applied to AndroidManifest.xml.

The following is an example manifest extension file:

    <?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/application">
            <uses-feature
                android:name="android.hardware.sensor.accelerometer"
                android:required="true"/>
        </target>
    </root>

The first line is a standard XML header. The second line contains the <root> tag with a fixed attribute, which has the same role as the <manifest> tag in AndroidManifest.xml.

The lines inside the <root> tag (except for <target> tags) are added to the <manifest> tag in AddroidManifest.xml without any changes or analysis.

The content of the <target> tags is added to AndroidManifest.xml part specified in the xpath="..." attribute.

You can have specific lines affect only specific packages by adding "%application.package%. ..." to those lines.

You can only add data to the following AndroidManifest.xml tags: <manifest> and </manifest/application>.

For the descriptions of uses-permission, uses-feature, and similar attributes, see the Android developer documentation.

We recommend that you do not add attributes that specify the maximum SDK version to uses-permission tags. This might cause conflicts when building applications with multiple add-ins.

## WINDOWS_RT_MANIFEST_EXTENSIONS.XML and WINDOWS_RT_PHONE_MANIFEST_EXTENSIONS.XML file descriptions

The builder uses the WINDOWS_RT_MANIFEST_EXTENSIONS.XML and WINDOWS_RT_PHONE_MANIFEST_EXTENSIONS.XML files for Windows Runtime and Windows Runtime Phone, respectively. This file describes the changes to AppxManifest.xml, such as the rights that an add-in requires to access specific application components or functionalities. These file are optional. If they are not available, no changes are applied to the permission settings.

The following is an example manifest extension file:

    <?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 first line is a standard XML header. The second line contains the <root> tag.

You can only add data to the <Additions> tag.

The xpath="..." attribute of the <target> tag specifies the target of "Name='XXXXX'" parameters in the AppxManifest.xml file.

For the descriptions of <Capability> and <DeviceCapability> tags, see the Windows developer documentation.

## 1C:Enterprise add-in naming rules

Since a mobile application might use multiple add-ins created by different developers, it is important to employ the following add-in naming rules to eliminate possible naming conflicts.

An add-in name can contain Roman characters and numbers. Spaces are not allowed. Underscore (_) is allowed. The first character must be a letter or an underscore (_). Add-in names are case-sensitive.

If an add-in is developed in a company that has a website (for example, 1c.com), the add-in name must begin with the site name in reverse order, with periods replaced by underscores (for example, com_1c). Then add another underscore(_) and the add-in name.

If the site name does not comply with the add-in naming rules, try the following:

- Replace prohibited characters, such as hyphens, with underscores.
- If a name matches a reserved word, add an underscore to the end.
- If a name starts with a number, add an underscore to the beginning.

## Add-in limitations

Keep in mind that an add-in can be attached both in a window application (thick client or thin client) and in a console application (for example, on a 1C:Enterprise server or in a web client) that can lack the main window, other windows, event queue, timers that use the event queue, and the option to set an event hook (for example, to the keyboard). You have to ensure the availability of the environment required for correct add-in operation.

In mobile platform add-ins, do not call the following methods from the system thread because an application might stop responding after an attempt to open a modal window:

- bool ADDIN_API Confirm (const WCHAR_T* queryText, tVariant* retval)
- bool ADDIN_API Alert (const WCHAR_T* text)

For Windows Runtime and Windows Runtime Phone, the option to load dynamic libraries from web publications is not implemented.

# Example descriptions

This delivery includes examples of add-in implementations developed using Native API and COM technologies, as well as extensions for Mozilla Firefox and Internet Explorer. A template that you can use for writing add-ins from scratch is also included.

Add-in implementations were made as much similar as possible (same identifiers, names, and so on) to simplify learning and analysis.

The example for a mobile platform is different due to mobile platform specifics, it is a simple pedometer. It is available in the \example\NativeAPIMobile directory.

The following sections describe the properties and methods implemented in the examples.

## 1C:Enterprise add-in examples for desktop computer

### Properties

IsEnabled

Usage: Read and write.

Description: Type: Boolean. Stores the add-in status.

IsTimerPresent

Usage: Read.

Description: Type: Boolean. Defines whether the add-in has a timer.

### Methods

Enable

Description:

Enables the add-in object.

Syntax:

Enable()

Disable

Description:

Disables the add-in object.

Syntax:

Disable()

ShowInStatusLine

Description:

Displays the specified text in the status bar for 5 seconds.

Syntax:

ShowInStatusLine(<Text>)

Parameters:

Text

Type: String. Text displayed in the status bar.

StartTimer

Description:

Starts the add-in timer. Every second the add-in sends a message with Component and Timer parameters and the system clock counter string.

Syntax:

StartTimer()

StopTimer

Description:

Stops the add-in timer.

Syntax:

StopTimer()

The component implemented using Native API also implements the LoadPicture() method.

LoadPicture

Description:

Loads a picture from the specified file and sends it to 1C:Enterprise as binary data.

Syntax:

LoadPicture(<FileName>)

Parameters:

FileName

Type: String. Picture file name.

ShowMessage

Displays the platform version.

Syntax:

ShowMessage()

## 1C:Enterprise add-in example for mobile platform

### Properties

IsEnabled

Usage: Read.

Description: Type: Boolean. Stores the add-in status.

### Methods

Enable

Description:

Enables the add-in object, starts a pedometer, and starts the tracking of movement type using accelerometers.
Every time the step count changes, the add-in generates a 1C:Enterprise event with "StepCounter", "OnChange", and "_" parameters.

Syntax:

Enable()

Disable

Description:

Disables the add-in object, resets the step count, and stops the tracking of movement type using accelerometers.

Syntax:

Disable()

GetStepCount

Description: Returns the step count accumulated since the call of the Enable() mentod.

Syntax:

GetStepCount()

Type: Integer.

GetMovementType

Description:

Returns the movement type index, one of the following:

0 - undefined

1 - no movement

2 - walk

3 - run

4 - car

5 - bike

Syntax:

GetMovementType()

Type: Integer.

GetDeviceOrientation

Description: Returns the angular orientation of the device in the earth-fixed coordinate system, in radians.

Syntax:

GetDeviceOrientation(<Plane>)

Parameters:

Plane - Cartesian plane whose data is requested (0 - XOY plane, 1 - XOZ plane, 2 - YOZ plane).

Type: Real.

ShowDeviceOrientation

Description: Shows a message with angular orientations of the device in the earth-fixed coordinate system, in radians.

Syntax:

ShowDeviceOrientation()

### Events

ExternEventProcessing

Description:

Occurs when an add-in sends a step count message.

Syntax:

Procedure ExternEventProcessing (Source, Event, Data)
If Source = "StepCounter" And Event = "OnChange" Then
...
EndIf
EndProcedure

Note. In this example <Data> = "_".

## Development tools

You can use the following development tools:

- Microsoft Visual C++,
- Delphi,
- C++ Builder,
- gcc