01 大纲
原文链接：
https://help.genesys.com/developer/cic/docs/icws/webhelp/ConceptualContent/GettingStarted_Libraries.htm#top
ICWS SDK 包含助手库多国语言，包括JavaScript，C＃，Objective-C的，和其他人简化常见API的用法。
这些帮助程序库ICWS直接镜像API，仅用于抽象低级HTTP请求和原始JSON对象格式。除了创建和发布有效的HTTP请求之外，这些库不会添加任何功能。
这些帮助类的语法库是ICWS API的镜像，仅用于抽象低级HTTP请求和原始JSON对象格式。除了创建和发布有效的HTTP请求之外，这些库不会添加任何功能。
有关详细信息，请参阅下面的特定主题，包括示例用法。
JavaScript语言特定库
原文链接：
https://help.genesys.com/developer/cic/docs/icws/webhelp/ConceptualContent/GettingStarted_Libraries_JavaScript.htm#top
JavaScript IC库提供了一种JavaScript的实现案例，可通过REST接口与IC服务器进行通信。该库主要是REST服务的一对一传递。它提供了一组对象，这些对象表示API提供的资源和对象。它抽象了执行低级HTTP请求和打包数据的工作，以便来回发送。
使用JavaScript层，您无需知道事物的确切URL，因为它可以为您提供有效的数据对象。
本节包含以下部分：
1、概述
2、连接
3、消息
4、把它放在一起：简单的例子
4.1、异步模块定义（AMD）示例
4.2、通用模块定义（UMD）示例
4.3、CommonJS示例
4.4、全局范围示例
一、概述
该库提供为AMD，CommonJS，UMD和全局范围库。REST API中的每个命名空间都作为JavaScript API中的单个模块提供。每个模块由资源和数据合同组成，资源始终以 connection.createConnection。函数的第一个参数将始终是一个参数对象，它是functionName.params类型的一个实例，例如$ connection.createConnection.params。第二个参数是一个对象，它是回调函数的HTTP响应代码映射。
在REST调用的结果中，库将执行对响应代码映射的查找以找到要调用的适当函数。除了包含响应代码的映射（例如200或404）之外，响应映射还可以包含以下特殊关键字：'abort'，'timeout'，'error'和'default'。每种方案都有多种处理程序，库可以调用最具体的处理程序。任何HTTP响应代码都将是搜索的第一个处理程序。否则，将对任何400或500级代码尝试“错误”。在中止服务器调用期间，将首先尝试'abort'，然后尝试'error'。在超时情况下，将首先尝试“超时”，然后尝试“错误”。在任何情况下，如果找不到其他匹配处理程序，将尝试“默认”。
二、连接
Connection和_util模块一起用于连接到IC服务器。在连接_util之前，必须调用setBaseUrl来设置哪些URL承载IC REST Web服务。
连接模块$ connection.createConnection创建与IC服务器的连接。createConnection.params的'header'属性采用所请求的语言，'content'属性采用BaseAuthConnectionRequestSettings派生对象。该对象将包含必要的连接参数，例如用户名和密码。
创建连接后，可以使用Connection模块和调用$ station.changeStationConnection来选择设置工作站。
三、消息
该Messaging模块用于从IC服务器检索消息。消息是在IC服务器上引发的事件，例如状态更改或正在添加的交互。如果使用短轮询，则消息将在服务器上排队，并应定期检索，因为一旦检索到一批消息，队列将再次开始填满。如果使用服务器发送的事件，则消息不会在服务器上排队，并在发生时发送。客户端应用程序应检查messaging功能版本以确定服务器是否支持服务器发送的事件。messaging版本2及更高版本支持服务器发送的事件。有关处理版本控制的详细信息，请参阅版本控制页面。
如果使用短轮询，则调用$messages.getMessages将从服务器请求批量消息。第二个参数callBacks是一个将响应代码（超时，错误，200,400等）映射到函数的对象。将根据服务器的响应调用相应的函数。如果结果为200，则回调的第二个参数将包含已接收的消息列表。该数组可能为空。
四、把它放在一起：简单例子
1、异步模块定义（AMD）示例
require(['_util', 'messaging', 'connection'], function(_util, messaging, connection){
// Set the base url so the library knows how to map its server calls
_util.setBaseUrl('https://HostServerName:HostPort');
// Variable to hold an EventSource instance in case server-sent events is supported.
var eventSource;
// Setup some connection parameters
var connectionParams = new connection.IcAuthConnectionRequestSettings();
connectionParams.applicationName = 'Example';
connectionParams.userID = 'username';
connectionParams.password = 'password';
// Connect to the IC server
connection.$connection.createConnection(
new connection.$connection.createConnection.params(
{
header: {
'Accept-Language': "en-US",
},
content: connectionParams,
// Setting the include query parameter to features so that
// the list of IC Server feature versions are available on
// the 201 connection response.
query: { 'include': 'features' },
}),
// The second parameter is a map of callbacks to execute based on the server response
{
'201': function (xhr, connectionResponse) {
// A 201 represents a successful connection, connectionResponse.alternateHostList are the paths
// to alternate servers.
var messagingVersion = 0;
// Store the messaging version, for use in determining if short-polling or
// server-sent events should be used.
if (connectionResponse.features) {
for (var i = connectionResponse.features.length - 1; i >= 0; i--) {
var featureObject = connectionResponse.features[i];
if (featureObject.featureId === 'messaging') {
messagingVersion = featureObject.version;
break;
}
}
}
// We can now set our station
var workstationSettings = new connection.WorkstationSettings();
workstationSettings.workstation = 'ExampleStation';
var stationParams = new connection.$station.changeStationConnection.params(
{
content: workstationSettings
});
connection.$station.changeStationConnection(stationParams,
{
'200': function(xhr, changeStationResponse) {
// Omitted: TODO, handle any post change station actions.
},
'401': handleChangeStationError,
'timeout': handleChangeStationError,
'default': handleChangeStationError,
'error': handleChangeStationError,
});
// Start message processing
startMessageProcessing(messagingVersion);
},
'401': handleConnectionError,
'timeout': handleConnectionError,
'default': handleConnectionError,
'error': handleConnectionError,
});
function handleConnectionError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleChangeStationError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function startMessageProcessing(messagingVersion) {
// Check to see if the IC Server and the browser supports server-sent events.
if (messagingVersion >= 2 && typeof EventSource !== 'undefined') {
startServerSentEventsMessageProcessing();
} else {
startShortPollingMessageProcessing();
}
}
function startShortPollingMessageProcessing() {
// Poll the server of any events that have occurred. This should be expected
// on a regular interval
// TODO: This example does not show putting this call in an interval
messaging.$messages.getMessages(
new messaging.$messages.getMessages.params({}),
// The second parameter is a map of callbacks to execute based on the server response
{
'200': function (xhr, messages) {
// messages contains an array of server side events that were retrieved
for (var i = messages.length - 1; i >= 0; i--) {
var message = messages[i];
handleMessage(message);
};
},
'401': handleMessageError,
'timeout': handleMessageError,
'default': handleMessageError,
'error': handleMessageError,
});
}
function startServerSentEventsMessageProcessing() {
if (!eventSource) {
var parameters = new Messaging.$messages.EventSource.params({});
eventSource = new Messaging.$messages.EventSource(parameters, { message: handleMessage });
};
}
function handleMessageError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleMessage(message) {
// Omitted: TODO, handle message
}
});
2、通用模块定义（UMD）示例
(function (root, factory) {
if (typeof exports === 'object') {
factory(exports, require('./_util'), require('./messaging'), require('./connection'));
} else if (typeof define === 'function' && define.amd) {
define(['exports', './_util', './messaging', './connection'], factory);
} else {
(function(parent) {
var namespaces = ['ININ','ICWS','Common'], childName;
while (childName = namespaces.shift()) {
if (!parent[childName]) {
parent = parent[childName] = {};
} else {
parent = parent[childName];
}
}
}(root));
factory(root.ININ.ICWS.Common, root.ININ.ICWS._util, root.ININ.ICWS.messaging, root.ININ.ICWS.connection);
}(this, function (exports, _util, messaging, connection) {
// Set the base url so the library knows how to map its server calls
_util.setBaseUrl('https://HostServerName:HostPort');
// Variable to hold an EventSource instance in case server-sent events is supported.
var eventSource;
// Setup some connection parameters
var connectionParams = new connection.IcAuthConnectionRequestSettings();
connectionParams.applicationName = 'Example';
connectionParams.userID = 'username';
connectionParams.password = 'password';
// Connect to the IC server
connection.$connection.createConnection(
new connection.$connection.createConnection.params(
{
header: {
'Accept-Language': "en-US",
},
content: connectionParams,
// Setting the include query parameter to features so that
// the list of IC Server feature versions are available on
// the 201 connection response.
query: { 'include': 'features' },
}),
// The second parameter is a map of callbacks to execute based on the server response
{
'201': function (xhr, connectionResponse) {
// A 201 represents a successful connection, connectionResponse.alternateHostList are the paths
// to alternate servers.
var messagingVersion = 0;
// Store the messaging version, for use in determining if short-polling or
// server-sent events should be used.
if (connectionResponse.features) {
for (var i = connectionResponse.features.length - 1; i >= 0; i--) {
var featureObject = connectionResponse.features[i];
if (featureObject.featureId === 'messaging') {
messagingVersion = featureObject.version;
break;
}
}
}
// We can now set our station
var workstationSettings = new connection.WorkstationSettings();
workstationSettings.workstation = 'ExampleStation';
var stationParams = new connection.$station.changeStationConnection.params(
{
content: workstationSettings
});
connection.$station.changeStationConnection(stationParams,
{
'200': function(xhr, changeStationResponse) {
// Omitted: TODO, handle any post change station actions.
},
'401': handleChangeStationError,
'timeout': handleChangeStationError,
'default': handleChangeStationError,
'error': handleChangeStationError,
});
// Start message processing
startMessageProcessing(messagingVersion);
},
'401': handleConnectionError,
'timeout': handleConnectionError,
'default': handleConnectionError,
'error': handleConnectionError,
});
function handleConnectionError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleChangeStationError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function startMessageProcessing(messagingVersion) {
// Check to see if the IC Server and the browser supports server-sent events.
if (messagingVersion >= 2 && typeof EventSource !== 'undefined') {
startServerSentEventsMessageProcessing();
} else {
startShortPollingMessageProcessing();
}
}
function startShortPollingMessageProcessing() {
// Poll the server of any events that have occurred. This should be expected
// on a regular interval
// TODO: This example does not show putting this call in an interval
messaging.$messages.getMessages(
new messaging.$messages.getMessages.params({}),
// The second parameter is a map of callbacks to execute based on the server response
{
'200': function (xhr, messages) {
// messages contains an array of server side events that were retrieved
for (var i = messages.length - 1; i >= 0; i--) {
var message = messages[i];
handleMessage(message);
};
},
'401': handleMessageError,
'timeout': handleMessageError,
'default': handleMessageError,
'error': handleMessageError,
});
}
function startServerSentEventsMessageProcessing() {
if (!eventSource) {
var parameters = new Messaging.$messages.EventSource.params({});
eventSource = new Messaging.$messages.EventSource(parameters, { message: handleMessage });
};
}
function handleMessageError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleMessage(message) {
// Omitted: TODO, handle message
}
});
3、CommonJS示例
var _util = require('_util'),
messaging = require('messaging'),
connection = require('connection');
// Set the base url so the library knows how to map its server calls
_util.setBaseUrl('https://HostServerName:HostPort');
// Variable to hold an EventSource instance in case server-sent events is supported.
var eventSource;
// Setup some connection parameters
var connectionParams = new connection.IcAuthConnectionRequestSettings();
connectionParams.applicationName = 'Example';
connectionParams.userID = 'username';
connectionParams.password = 'password';
// Connect to the IC server
connection.$connection.createConnection(
new connection.$connection.createConnection.params(
{
header: {
'Accept-Language': "en-US",
},
content: connectionParams,
// Setting the include query parameter to features so that
// the list of IC Server feature versions are available on
// the 201 connection response.
query: { 'include': 'features' },
}),
// The second parameter is a map of callbacks to execute based on the server response
{
'201': function (xhr, connectionResponse) {
// A 201 represents a successful connection, connectionResponse.alternateHostList are the paths
// to alternate servers.
var messagingVersion = 0;
// Store the messaging version, for use in determining if short-polling or
// server-sent events should be used.
if (connectionResponse.features) {
for (var i = connectionResponse.features.length - 1; i >= 0; i--) {
var featureObject = connectionResponse.features[i];
if (featureObject.featureId === 'messaging') {
messagingVersion = featureObject.version;
break;
}
}
}
// We can now set our station
var workstationSettings = new connection.WorkstationSettings();
workstationSettings.workstation = 'ExampleStation';
var stationParams = new connection.$station.changeStationConnection.params(
{
content: workstationSettings
});
connection.$station.changeStationConnection(stationParams,
{
'200': function(xhr, changeStationResponse) {
// Omitted: TODO, handle any post change station actions.
},
'401': handleChangeStationError,
'timeout': handleChangeStationError,
'default': handleChangeStationError,
'error': handleChangeStationError,
});
// Start message processing
startMessageProcessing(messagingVersion);
},
'401': handleConnectionError,
'timeout': handleConnectionError,
'default': handleConnectionError,
'error': handleConnectionError,
});
function handleConnectionError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleChangeStationError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function startMessageProcessing(messagingVersion) {
// Check to see if the IC Server and the browser supports server-sent events.
if (messagingVersion >= 2 && typeof EventSource !== 'undefined') {
startServerSentEventsMessageProcessing();
} else {
startShortPollingMessageProcessing();
}
}
function startShortPollingMessageProcessing() {
// Poll the server of any events that have occurred. This should be expected
// on a regular interval
// TODO: This example does not show putting this call in an interval
messaging.$messages.getMessages(
new messaging.$messages.getMessages.params({}),
// The second parameter is a map of callbacks to execute based on the server response
{
'200': function (xhr, messages) {
// messages contains an array of server side events that were retrieved
for (var i = messages.length - 1; i >= 0; i--) {
var message = messages[i];
handleMessage(message);
};
},
'401': handleMessageError,
'timeout': handleMessageError,
'default': handleMessageError,
'error': handleMessageError,
});
}
function startServerSentEventsMessageProcessing() {
if (!eventSource) {
var parameters = new Messaging.$messages.EventSource.params({});
eventSource = new Messaging.$messages.EventSource(parameters, { message: handleMessage });
};
}
function handleMessageError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleMessage(message) {
// Omitted: TODO, handle message
}
4、全局范围示例
(function(root){
var _util = root.ININ.ICWS._util;
var messaging = root.ININ.ICWS.messaging;
var connection = root.ININ.ICWS.connection;
// Set the base url so the library knows how to map its server calls
_util.setBaseUrl('https://HostServerName:HostPort');
// Variable to hold an EventSource instance in case server-sent events is supported.
var eventSource;
// Setup some connection parameters
var connectionParams = new connection.IcAuthConnectionRequestSettings();
connectionParams.applicationName = 'Example';
connectionParams.userID = 'username';
connectionParams.password = 'password';
// Connect to the IC server
connection.$connection.createConnection(
new connection.$connection.createConnection.params(
{
header: {
'Accept-Language': "en-US",
},
content: connectionParams,
// Setting the include query parameter to features so that
// the list of IC Server feature versions are available on
// the 201 connection response.
query: { 'include': 'features' },
}),
// The second parameter is a map of callbacks to execute based on the server response
{
'201': function (xhr, connectionResponse) {
// A 201 represents a successful connection, connectionResponse.alternateHostList are the paths
// to alternate servers.
var messagingVersion = 0;
// Store the messaging version, for use in determining if short-polling or
// server-sent events should be used.
if (connectionResponse.features) {
for (var i = connectionResponse.features.length - 1; i >= 0; i--) {
var featureObject = connectionResponse.features[i];
if (featureObject.featureId === 'messaging') {
messagingVersion = featureObject.version;
break;
}
}
}
// We can now set our station
var workstationSettings = new connection.WorkstationSettings();
workstationSettings.workstation = 'ExampleStation';
var stationParams = new connection.$station.changeStationConnection.params(
{
content: workstationSettings
});
connection.$station.changeStationConnection(stationParams,
{
'200': function(xhr, changeStationResponse) {
// Omitted: TODO, handle any post change station actions.
},
'401': handleChangeStationError,
'timeout': handleChangeStationError,
'default': handleChangeStationError,
'error': handleChangeStationError,
});
// Start message processing
startMessageProcessing(messagingVersion);
},
'401': handleConnectionError,
'timeout': handleConnectionError,
'default': handleConnectionError,
'error': handleConnectionError,
});
function handleConnectionError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleChangeStationError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function startMessageProcessing(messagingVersion) {
// Check to see if the IC Server and the browser supports server-sent events.
if (messagingVersion >= 2 && typeof EventSource !== 'undefined') {
startServerSentEventsMessageProcessing();
} else {
startShortPollingMessageProcessing();
}
}
function startShortPollingMessageProcessing() {
// Poll the server of any events that have occurred. This should be expected
// on a regular interval
// TODO: This example does not show putting this call in an interval
messaging.$messages.getMessages(
new messaging.$messages.getMessages.params({}),
// The second parameter is a map of callbacks to execute based on the server response
{
'200': function (xhr, messages) {
// messages contains an array of server side events that were retrieved
for (var i = messages.length - 1; i >= 0; i--) {
var message = messages[i];
handleMessage(message);
};
},
'401': handleMessageError,
'timeout': handleMessageError,
'default': handleMessageError,
'error': handleMessageError,
});
}
function startServerSentEventsMessageProcessing() {
if (!eventSource) {
var parameters = new Messaging.$messages.EventSource.params({});
eventSource = new Messaging.$messages.EventSource(parameters, { message: handleMessage });
};
}
function handleMessageError(xhr) {
// Omitted: TODO, handle xhr.status / xhr.response
}
function handleMessage(message) {
// Omitted: TODO, handle message
}
})();