Tutorial on start using the API

From LIVECHAT Developer Zone Wiki

Jump to: navigation, search

In this tutorial you will learn about how to build and install your own add-on for LIVECHAT Contact Center application.

Contents

Overview

The Integration API consists of set of services and data structures that can operate on internal methods and data members of the solution. Using the API you will be able to create new add-ons, automate system management tasks and integrate with other proprietary back office software (CRM, call center software, etc). This documentation will be a guided tour through the basic operations using the client side API. The complete API reference and developer documentation will help you to learn all about the API.

Sample add-on

You will find here sample client side add-on project file. This will help you to understand the basic idea and basic data structures of the API. Download it here: SampleAddon.zip, unzip and open the solution using the Microsoft Visual Studio.

Important note: before you start read the requirements to successfully compile and build this solution.

Solution overview

The soulution includes the following files:

The rest of files in the solution are standard files generated by the AppWizzard.


Successfully compiled sample solution will create native DLL file written in C++ language. This DLL file will have three exported methods, used to communicate with the application:

  • PLUGININFO* plugin_info(DWORD version)
  • HWND load(HINSTANCE instance, HWND hwnd)
  • int unload()


When the DLL file is loaded in memory, the application calls plugin_info(version) method to get the basic informations about the add-on. Version parameter is used to present the application's version number. This number can be used to restrict the add-on to run on specified application version.

Next the load(instance, hwnd) method is called where instance parameter is the handle to an instance of the application and the hwnd parameter is the handle to a main window of the application. Method returns handle to the second window, created by the add-on. This window is created automatically when load method is executed.

Both windows are used for communications purposes using the Microsoft Windows SendMessage function. When you call specified service in the application (see API reference and developer documentation) you must use the call method. This will send special message to the application's main window and will execute called service procedure. Note this method does not return until the service procedure has processed the message. Application communicates with add-on using the handle to a window returned by the load() method. You can handle that message in the on_command method.

Class definition

A class is a type definition of an addon's basic object. Every addon must have a definition of the class derived from CPlugin (principal base class). This class is responsible for representing the addon. You must define the name, display name, version, description, author, copyright and type of the add-on.

class SamplePlugin : public CPlugin {
public:
	BEGIN_PLUGIN_INFO(SamplePlugin)
		PLUGIN_NAME		(_T("sampleplugin"))
		PLUGIN_DISPNAME		(_T("Sample Plugin"))
		PLUGIN_VERSION		(PLUGIN_MAKE_VERSION(1,0,0,1))
		PLUGIN_DESCRIPTION	(_T("Sample Plugin"))
		PLUGIN_AUTHOR		(_T("LIVECHAT Software"))
		PLUGIN_COPYRIGHT	(_T("None"))
		PLUGIN_TYPE		(0)
	END_PLUGIN_INFO()
};

Next you need to define one global variable. You should restrict the code to instantiate a class to one object. Exactly one object is needed to coordinate actions across the API system.
Go to SamplePlugin.cpp for details: 

SamplePlugin gPlugin; // one instance of the sample plugin

Implementation

In your custom class definition file you can define following methods:

  • int on_load() - addon is loaded by the application
  • int on_unload() - addon is unloaded by the application
  • int on_command(LPCTSTR cmd, LPARAM wParam, WPARAM lParam) - listener for commands being executed

Return values: The return value specifies the result of the executed method. When operation succeeded API_SUCCESS is returned or API_ERROR when somethink went wrong.
In the sample add-on we create a button with a caption, icon and tooltip in the add-ons tab of the main window ribon bar. There is also an example how to handle button pressed event. Take a look at the implemention file: 

int SamplePlugin::on_load() 
{
	LCTOOLBARITEM item = {0};
	item.cbSize = sizeof(LCTOOLBARITEM);
	item.plugin_name = name();
	item.id = 1;
	item.caption = _T("Test");
	item.icon = LoadIcon(mInstance , MAKEINTRESOURCE(IDI_ICON1));
	item.tooltip = _T("Sample tooltip");
	item.position = 0;
	item.menu = 0;
	item.service = _T("OnButtonClick");
	
	call(SVC_ADD_TOOLBARITEM, 0, (LPARAM) &item);
	
	return API_SUCCESS;
}

int SamplePlugin::on_unload() 
{
        // You don't need to destroy toolbar. It's done by the application.
	return API_SUCCESS;
}

int SamplePlugin::on_command(LPCTSTR cmd, LPARAM wParam, WPARAM lParam)
{
	if (_tcscmp(cmd, _T("OnButtonClick") ) == 0)
	{
		MessageBox(0, _T("Button pressed"), name(), MB_OK);
		
		return API_SUCCESS;
	}

	return API_ERROR;
}

Deployment

All add-ons must be installed in one of the following folders:

  • application data folder of user's profile (c:\Documents and Settings\User name\Application data\LIVECHAT\Plugins on WinXP, c:\Users\User name\AppData\Roaming\LIVECHAT\Plugins on Vista)

First folder is used by add-ons included in standard installation file. Second one is used for all other custom add-ons created by third-party developers.

You can manually install add-on using the application's Add-ons Manager window (go to Tools->Add-ons Manager). Then use the "Add new..." button to install your add-on to the application data folder. Please note you will be prompted to restart the application to successfully finish the installation process.

Add-ons manager window:
Image:Addons-manager.png

Retrieved from "http://wiki.livechatinc.com/index.php/Tutorial_on_start_using_the_API"
Personal tools