Creating add-ins with Native API technology

Content

Creating add-ins with Native API technology
Add-in interface
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
Localization

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:

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.

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.

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\

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.