External API

Back to index page

What is external API?

External API is library defined typically for external usage, which means to produce JC4XL document silently by a service in the background, or interactively attach to running Excel instances and extend the sheets with JC4XL structures from a different desktop application.

 

How to access it?

From VBA, add the reference from Tools/Reference

Menu.InternalAPI

 

AvailableRef.ExternalAPI (1.1 Type Library from JC4XL 1.1.4)

 

From C++, add the references into your stdafx.h module

#import "libid:2D09FA5A-9FD9-46E6-A4E3-3327BF6E48EB" raw_interfaces_only named_guids

using namespace JChemExcelCOMInterfacesLib;

 

#import "libid:3ADEBF5E-5174-42B9-9EA4-C7FB03B2C427" raw_interfaces_only named_guids

using namespace JChemExcelAPILib;

 

and compile stdafx.cpp afterwards.

 

From C# project, add the references of the delivered interop assembly modules to your project

Form.SolutionExplorer.ExternalAPI

 

or browse the COM library similarly how it was described in the first point (VBA)

 

Helper functions in External API library

The library contains several functions, properties defined on ExternalAPI COM object to help you access the running JC4XL instances and provide some additional routine prior to using the real API calls (see API Interface section above). Helpers are useful since not necessary to include Excel reference to operate with API routines. (Available versions are 1.0 and 1.1).

Function/Property Name

Parameters

Optional

Type in COM

Type in VBA

Type in C#/Java

DefaultFileExtension
(property)
(1.0)

Return value

(determines the installed Excel version and its default file extension for generating file name from the host application)

 

BSTR*

string

string

ActiveInstance
(property)
(1.0)

newVal
(new active instance id the API calls will be affected)

N

BSTR

string

string

 

Return value

 

BSTR*

string

string

KeepInstanceAlive
(property)
(1.0)

newVal
(this is when creating a new workbook, after creation it should be displayed and kept open)

N

VARIANT_BOOL

boolean

boolean

 

Return value

 

VARIANT_BOOL*

boolean

boolean

GetInstanceIds
(1.0)

Return value
(gives back all running instances)

 

SAFEARRAY(BSTR)*

Dim () as string

string[]

GetWorkbooks
(1.0)

Return value
(gives back all workbooks belonging to the active instance)

 

SAFEARRAY(BSTR)*

Dim () as string

string[]

GetWorksheets
(1.0)

workbookId
(workbook name in the active instance)

N

BSTR

string

string

 

Return value
(gives back all worksheets belonging to the active instance and the specified workbook id)

 

SAFEARRAY(BSTR)*

Dim () as string

string[]

GetInstanceDisplayName
(1.0)

instanceId

N

BSTR

string

string

 

Return value
(display name for the specified instance id)

 

BSTR*

string

string

 

Before calling any of main API functions the active instance should be set on the External API object. Available Excel and JC4XL plug-in instances can be retrieved by calling GetInstanceIds function. Instance id list includes the „New Instance” constant as well for creating new hidden or visible JC4XL workbook instances (for JC4XL document service purposes).

 

How to instantiate External API?

From VBA

Dim api As JChemExcelAPILib.ExternalAPI
   Set api = New JChemExcelAPILib.ExternalAPI

 

From C#

private var api = new JChemExcelAPILib.ExternalAPIClass();

 

From C++

JChemExcelAPILib::IExternalAPIPtr api;
api.CreateInstance(JChemExcelAPILib::CLSID_ExternalAPI);

or

api.CreateInstance(__uuidof(JChemExcelAPILib::ExternalAPI));