Introduction

Congree can be integrated in different content editors. Most of these editors are separate applications that run in their own process and provide an API for integration and content manipulation (e.g. Microsoft Word, Adobe InDesign, JustSystems XMetaL Author). Each editor's API is very specific. Congree has to use different approaches for integration. However, there are also many editors (e.g. Richedit, XMAX etc.) that do not have their own process and are designed to be placed in other applications. Obviously, Congree does not know how to integrate itself into these applications and has no connection to the built-in editors. In order to cover this scenario, Congree provides the API for ISV applications. The API can be used to by various applications that use built-in editors to integrate Congree. The API is COM specific (https://en.wikipedia.org/wiki/Component_Object_Model) and therefore can be used by programs written in different languages.

The basis is the following idea:

• To display Congree panels, Congree provides a special ActiveX (http://en.wikipedia.org/wiki/ActiveX) AxPlaceHolderControl component. This component is a container for the display elements of Congree (the display elements of Congree is a Congree panel, e.g. Language Check Panel, Terminology Research Panel, etc.). For each Congree panel, the application should host an appropriate AxPlaceHolderControl. Each instance of AxPlaceHolderControl should be assigned a predefined identifier (see Table 1). This identifier serves Congree as a marker, which tells Congree what type of Congree panel should be embedded in a particular placeholder.

• The application should create an instance of the Congree bootstrapper co-class and obtain (via QueryInterface https://docs.microsoft.com/en-us/cpp/atl/queryinterface?view=vs-2019) the ICongreeBootstrapper interface. ICongreeBootstrapper represents the instance of a Congree application.
• Through the CreateControlContext method of the ICongreeBootstrapper, the application associates an instance of the editor object (editor control) as well as instances of the AxPlaceHolderControl placeholder elements in which the check results will be displayed.

After creating the control context, Congree will have all the necessary information to access the editor control's API and will be able to place the corresponding Congree panels in the placeholders. The Congree panels will display information corresponding to the contents of the editor instance.

Congree also provides a standard Congree toolbar which has its own ID and can be also embedded in AxPlaceHolderControl.

                                                                                                                                               Fig.1. Congree toolbar  

Congree API for ISV applications

ICongreeBootstrapper

The ICongreeBootstrapper interface represents the instance of Congree application. The main method which exposes ICongreeBootstrapper is CreateControlContext which returns the instance of ICreateControlContext. Each instance of ICreateControlContext holds the connection between the editor (control) and the Congree placeholders. The type of the editor should be well known to Congree. Each instance of the editor must have its own context (one document is one context).

[
odl,
uuid(F1F2935F-1AA3-3DC1-B3CE-86F36B8BDEEA),
version(1.0),
dual,
oleautomation
]
interface ICongreeBootstrapper : IDispatch 
{
	[id(0x00000001)]
	HRESULT Destroy();
 
	[id(0x00000002)]
	HRESULT CreateControlContext([in] VARIANT control, [in] VARIANT placeHolders, [out, retval] IControlContext** pRetVal);
 
	[id(0x00000003), propget]
	HRESULT AuthorizationManager([out, retval] IAuthorizationManager** pRetVal);
 
	[id(0x00000004), propget]
	HRESULT PanelInfos([out, retval] SAFEARRAY(IPanelInfo*)* pRetVal);
 
	[id(0x00000005), propget]
    HRESULT Contexts([out, retval] SAFEARRAY(IControlContext*)* pRetVal);
 
	[id(0x00000006)]
	HRESULT Initialize([in] BSTR thirdPartySystemIdentifier);
};

Methods

Initialize

Initialize the Congree application. You should call this method after creating the ICongreeBootstrapper. Use thirdPartySystemIdentifier parameter if it is necessary to initialize Congree with predefined third-party system identifier.

Parameters 

BSTR thirdPartySystemIdentifier - 

Remark: The thirdPartySystemIdentifier can be empty

Destroy

Destroys the Congree application.

Remarks: You should call the Destroy when the instance of Congree is no longer in use.

CreateControlContext

Creates the instance of ICreateControlContext which binds the editor (control) with Congree placeholders.

Parameters

VARIANT control - The COM object that defines the editor. E.g it can be specific ActiveX control or other well known for Congree COM object which provides access to the editor. 

VARIANT placeHolders - The collection of AxPlaceHolderControl controls. The argument can be either collection (SAFEARRAY) of AxPlaceHolderControl or certain AxPlaceHolderControl ActiveX control. 

Remark: Each placeholder is used by Congree as the container to place inside the specific Congree panel (e.g. Terminology Research Panel). The placeholder is the ActiveX object, which is installed with Congree and registered in the operating system. Thus, for example, if you are using WinForms, you can simply open the list of ActiveX components and drag the AxPlaceHolderControl to the form. For each Congree panel you want to use in your application, you need to create an AxPlaceHolderControl.

Returns

The instance of IControlContext.

Properties

PanelInfos

Returns

Returns a collection of IPanelInfo.

Remark: IPanelInfo provides information about Congree panel. Congree is modular application and consists of many modules (extensions). Each module implements its own collection (one or more) of Congree panels (e.g. Language Check Panel, Authoring Memory Panel, Terminology Research Panel and so on). The PanelInfos contains description of each available Congree panel from all loaded modules.

You can disable module via Extensions page in the Congree Authoring Client settings.

AuthorizationManager 

Returns

Returns the instance of IAuthorizationManager.

IControlContext

The instance of IControlContext is responsible for binding external editor (control) with Congree placeholders (AxPlaceHolderControl).

[
odl,
uuid(9BBB1115-247D-3B83-BD73-A7A034B9415D),
version(1.0),
dual,
oleautomation
]
interface IControlContext : IDispatch 
{
	[id(0x00000001), propget]
	HRESULT Control([out, retval] VARIANT* pRetVal);

	[id(0x00000002)]
	HRESULT Close();

	[id(0x00000003)]
	HRESULT AddPlaceholders([in] VARIANT placeHolders);

	[id(0x00000004)]
	HRESULT ReleasePlaceholders([in] VARIANT placeHolders);

	[id(0x00000005)]
	HRESULT UpdatePlaceholders();
 
	[id(0x00000006), propget]
	HRESULT Report([out, retval] IReporting** pRetVal);
};

Methods

Close

Closes the control context. Use this method to close the control context and free resources. You should use it e.g. when the user closes the page with the editor.

AddPlaceholders

Adds new placeholders to the control context. With this method you can dynamically add some Congree panels.

Parameters

VARIANT placeHolders - The collection of AxPlaceHolderControl controls.

Remark: This can be useful in the following scenario:

For example, some user works with your application and sees only the Language Check Panel. A little later, he decides to look at the Term Candidates Panel. In order to show this Congree panel, you should create a new AxPlaceHolderControl,  set the ClientID of the AxPlaceHolderControl to the "Congree.TerminologyCandidates.Panel" and add the AxPlaceHolderControl to the control context. After that Congree will place the corresponding Congree panel inside of the placeholder.

ReleasePlaceholders

Releases the certain placeholder from the control context.

Parameters

VARIANT placeHolders - The collection of AxPlaceHolderControl controls.

Remark: You should use this method to release the placeholder from the certain context when, e.g., user closes some window which contains the placeholder.

UpdatePlaceholders

Updates contents of all placeholders of the control context.

Remark: This method should be used when you have shared placeholders for different control contexts (see Fig.3). This scenario is useful when the application is MDI (https://en.wikipedia.org/wiki/Multiple_document_interface). Typically, an MDI application has many documents and one instance of each Congree panel. Thus, Congress displays the results of the check for the active document (Editor control). Congree knows nothing about the fact which document (Editor control) is active for the application. To inform Congree for which document it is necessary to display the results of the check, the application has should call the UpdatePlaceholders for the control context associated with the document (Edit control).

Properties

Control

Returns the editor control passed to the CreateControlContext method of ICongreeBootstrapper.

Report

Returns the instance of IReporting.

The application can have several instances of the editor (e.g. several instances of XMax or Proxy Editor). Each instance of the editor has to be bound with a set of AxPlaceHolderControl placeholders. Congree uses the placeholder as a container in which the corresponding Congree panel (e.g. Language Check Panel, Terminology Research Panel) will be placed.

 A set of placeholders can be created for each instance of the editor (Fig.2)

Fig.2. Each control context has its own set of Congree Authoring Client placeholders.

They can also be shared between different instances of the editor (Fig.3).

Fig.3. Congree Authoring Client placeholders are shared between different control contexts.

IPanelInfo

Provides information about Congree panels. Congree is modular application and consists of many modules (extensions). Each module implements its own collection (one or more) of Congree panel (e.g. Language Check Panel, Authoring Memory Panel, Terminology Research Panel and so on). 

[
odl,
uuid(C2D43E52-ABB3-4065-8317-C27C5FD0C47F),
version(1.0),
dual,
oleautomation
]
interface IPanelInfo : IDispatch 
{
	[id(0x00000001), propget]
	HRESULT ClientID([out, retval] BSTR* pRetVal);

	[id(0x00000002), propget]
	HRESULT DisplayName([out, retval] BSTR* pRetVal);

	[id(0x00000003), propget]
    HRESULT Image([out, retval] IUnknown** pRetVal);

    [id(0x00000004), propget]
    HRESULT PreferedHorizontal([out, retval] VARIANT_BOOL* pRetVal);
};

Methods

Properties

ClientID

Returns the unique Congree panel id. The list of Congree panel IDs you can find in the Table 1.

Remarks: The ID is used to specify the Congree of what type of Congree panel should be placed in the placeholder. For more information, see the description of IAxPlaceHolderControl.

DisplayName

Returns the official name of a particular Congree panel.

Remarks: Application can use this name, e.g., in menu or as a caption for the windows in which the Congree panel is embedded.

IReporting

This instance of IReporting provides access to a check report for a particular document. The report is gathered based on information received from the loaded modules (e.g. Linguistic Check and so on.).

[
 odl,
 uuid(77033B18-D3DE-43D4-8C19-0360A28EB1F2),
 version(1.0),
 dual,
 oleautomation
]
interface IReporting : IDispatch
{
		[id(0x00000001)]
		HRESULT GetReport([in] BSTR modules, [out, retval] BSTR* pRetVal);
};

Methods

GetReport

Returns the check report. The report is XML based document.

Parameters 

BSTR modules - a list of modules for which a report is required.  The list of modules must be listed via ";". The allowed list of names you can find in the this table

Returns

Returns the XML document as string which contains the report.

AxPlaceHolderControl

Congree allows embedding Congree panels (such as Language Check Panel, Terminology Research Panel and so on) in other applications. The AxPlaceHolderControl (ActiveX) component is used as a container for the Congree panels. This ActiveX control is installed with Congree and is registered in the operating system.

Thus, you can immediately use it in your application as, e.g, it is shown in Fig.4.

Fig.4. The AxPlaceHolderControl ActiveX control embedded in a WinForms application

The AxPlaceHolderControl implements, except standard ActiveX interfaces, also the IAxPlaceHolderControl interface.

object,
uuid(404BD0E3-2D44-4795-8C68-D40FE794F0B4),
dual,
nonextensible,
pointer_default(unique)
]
interface IAxPlaceHolderControl : IDispatch
{
	[propput, bindable, requestedit, id(DISPID_AUTOSIZE)]
	HRESULT AutoSize([in]VARIANT_BOOL vbool);

	[propget, bindable, requestedit, id(DISPID_AUTOSIZE)]
	HRESULT AutoSize([out,retval]VARIANT_BOOL* pbool);

	[propget, bindable, requestedit, id(DISPID_HWND)]
	HRESULT HWND([out, retval]LONG_PTR* pHWND);

	[propput, bindable, requestedit, id(DISPID_CAPTION)]
	HRESULT Caption([in]BSTR strCaption);
 
	[propget, bindable, requestedit, id(DISPID_CAPTION)]
	HRESULT Caption([out,retval]BSTR* pstrCaption);

	[propput, bindable, requestedit, id(1)]
	HRESULT ClientID([in]BSTR val);
	[propget, bindable, requestedit, id(1)]
	HRESULT ClientID([out,retval]BSTR* pVal);

	[propput, id(2)]
	HRESULT Client([in] IUnknown* pVal);

	[propget, id(2)]
	HRESULT Client([out,retval] IUnknown** ppVal);
};
 
[
uuid(D07DB8E1-43C9-4D6F-94A1-1F2B060A22E0),
control
]
co-class AxPlaceHolderControl 
{
	[default] interface IAxPlaceHolderControl;
};

The IAxPlaceHolderControl exposes the ClientID property. This property has one of the predefined values from Table 1. It has to be set by the application in advance, before an instance of this object is passed to the function CreateControlContex.

The list of possible values can be found in Table 1.

Table 1

Table 1 contains the list of IDs of the Congree panels which are implemented by different modules of the Congree Authoring Client. If some module is disabled (via Extensions in the Congree Authoring Client settings), the corresponding Congree panel will not be loaded and, therefore, will not be displayed even though the placeholder for this Congree panel exists.

It is also possible to get this list dynamically through the ClientID property of the IPanelInfo interface.

Fig.5 shows the standard application layout which embeds placeholders for different Congree panels.

Fig.5. The layout of application which embeds placeholders for different Congree panels

Fig.6. shows the same application with loaded Congree panels.

Fig.6. The application with loaded Congree Authoring Client panels in the corresponding placeholders

IAuthorizationManager

Some applications want to control the process of logging in and logging out Congree themselves. These applications may use a different type of authentication as well. Therefore, the application can use IAuthorizationManager.

[
odl,
uuid(8CE6961F-9626-357B-92B8-BB6AE1AC72D6),
version(1.0),
dual,
oleautomation
]
interface IAuthorizationManager : IDispatch 
{
	[id(0x00000001)]
	HRESULT Login([out, retval] VARIANT_BOOL* pRetVal);

	[id(0x00000002)]
	HRESULT Logout();

	[id(0x00000003)]
	HRESULT SetClientCredentials([in] IClientCredentials* credentials);
 
	[DispId(0x00000004)]
	void SetAuthenticationType(string authenticationType);
};

Methods:

Login

Logs in Congree and locks the license.

Remark: Some type of authentication requires additional parameters, such as, for example, a login and password. Before the Login call, set the required authentication type via SetAuthenticationType and credentials via SetClientCredentials.

Logout

Logs out and release the license.

SetClientCredentials

Sets the credentials.

Remark: You should set additional credentials if it requires the certain type of authentication. Congree provides specific co-classes which implement IClientCredentials interface. E.g. one of them is UserNamePasswordClientCredentialComShim. This co-class implements the IUserNamePasswordClientCredential interface which is Inherited from IClientCredentials. This interface allows setting login and password.

SetAuthenticationType

Sets the Congree authentication type.

Remarks: Congree supports different type of authentication modes. These modes cover different authentication scenarios.

Authentication modes are:

• • Congree standard (username + password)

    • Display name: "Congree"
    • Guid:  00000000-0000-0000-0000-000000000000
    • Support user auto-creation:  no
    • User name and password can be changed from the login dialog

  • Trust CMS (username + certificate)

    • Display name: "Trust CMS"

    • Guid: 0630805F-EC32-4331-BCC8-FDAD2C59B6AD

    • Support user auto-creation:  yes

    • User name can not be changed from the login dialog. User name is provided by CMS via API only.

  • Trust Domain (username and domain are obtained from windows identity + certificate)

    • Display name: "Trust Domain"
    • Guid: B3ABBF2E-5909-4783-A13F-8AC8F1108C74
    • Support user auto-creation:  yes
    • User name can not be changed at all. Domain and user name are obtained from Windows current user identity.

  • Windows authentication (based on kerberos token + certificate)

    • Display name: "Trust Windows"

    • Guid: 53B8D8B6-CBF8-45F4-A198-5EF3AAC09C78

    • Support user auto-creation:  yes

    • User name and password can not be changed at all. Windows kerberos token is used. 

To specify an authentication type other than default, you should call the SetAuthenticationType and pass either the display name of the Guid or the corresponding authentication type.

Remark: It is better to pass the Guid, because the display name is localizable.

"Trust Domain", "Trust Windows" use current user Windows identity credentials and do not require additional arguments. The authentication types such as "Congree", "Trust CMS" require username and password / username correspondingly. To provide them the instance of IUserNamePasswordClientCredential is used.

By default, all authentication types, except Congree standard, are deactivated. To activate the appropriate authentication type, you should go to the Congree Control Center and associate the corresponding authentication type with Congree user groups. If authentication type supports auto-creation, the Congree Server automatically creates an user the first time it connects. The user will be created in a group that is associated with this authentication type. Next, the administrator can open Congree Control Center and change some information for the new user.

IUserNamePasswordClientCredential

The IUserNamePasswordClientCredential is designed to set Congree Authoring Client credentials from code, rather than from the login dialog. It provides methods which allow the application to specify the user credentials.

[
odl,
uuid(60667015-64B2-38A7-9B4C-0C714A968EC3),
version(1.0),
dual,
oleautomation,
]
interface IUserNamePasswordClientCredential : IDispatch 
{
	[id(0x00000001), propget]
	HRESULT UserName([out, retval] BSTR* pRetVal);
 
	[id(0x00000001), propput]
	HRESULT UserName([in] BSTR pRetVal);
 
	[id(0x00000002), propget]
	HRESULT Password([out, retval] BSTR* pRetVal);
 
	[id(0x00000002), propput]
	HRESULT Password([in] BSTR pRetVal);
};

Properties

UserName

Sets or gets the user name.

Password

Sets or gets the user password.

Remark: Congree provides the UserNamePasswordClientCredentialComShim co-class which implements IUserNamePasswordClientCredential interface and internally is Inherited from IClientCredentials. 

[
  uuid(B61662BC-A7D4-4677-A9BA-93E24F78946B)
]
co-class UserNamePasswordClientCredentialComShim 
{
    interface IUserNamePasswordClientCredential;
};
 
The ProgId of the co-class is "Congree.ServiceModel.Description.UserNamePasswordClientCredential.ComShim".

How to use this API

ICongreeBootstrapper bootstrapper = ... // create a Congree bootstrapper co-class (e.g. it can be bootstrapper for XMax or ProxyEditor)

// initialize Congree
bootstrapper.Initialize(null);
 
// create the collection of placeholders. 
// AxPlaceHolderControl1, AxPlaceHolderControl2, ... AxPlaceHolderControln are instances of the AxPlaceHolderControl ActiveX control
var placeholders = new [] { AxPlaceHolderControl1, AxPlaceHolderControl2, ... AxPlaceHolderControln);
 
// editorInstance is COM instance of Editor control (e.g. ProxyEditor or XMax control). 
var controlContext = bootstrapper.CreateControlContext(editorControlInstance, placeholders);
 
// set the Trust CMS authentication type
IAuthorizationManager authorizationManager = congreeXMax.AuthorizationManager;
authorizationManager.SetAuthenticationType("0630805F-EC32-4331-BCC8-FDAD2C59B6AD");

IUserNamePasswordClientCredential credentials = (IUserNamePasswordClientCredential)new UserNamePasswordClientCredentialComShimClass();
credentials.UserName = "Default";
 
authorizationManager.SetClientCredentials(credentials);

bool result = authorizationManager.Login();
 
// application runtime
 
....
 
controlContext.Close();
 
...
 
bootstrapper.Destroy();

Subpages

• Congree API for Proxy Editor
• Congree API for Structure Editor
• Congree API for XMetaL© XMAX and Proxy Editor Manual