Citrix Virtual Channel SDK for Citrix Workspace app for HTML5

global

March 6, 2024

Contributed by:

Type Definitions

driverClose(msg)

Callback that gets called when the virtual channel is closed for a session. Do any cleanup of the virtual channel in your implementation inside the callback.

Parameters

Name	Type	Description
`msg`	driverCloseMsg	Details of the session containing the session id and virtual channel name.

Example

//Driver close for CTXPING virtual channel. You can handle any cleanup for each session.
    function pingDriverClose(msg){
        console.log("driver close received for stream " + msg["streamName"] + " for session " + msg["sessionId"]);
    }
<!--NeedCopy-->

driverCloseMsg

Contains the details of the session for which the virtual channel is closed.

Type

Object

Properties

Name	Type	Description
`driverCloseMsg.sessionId`	string	Id of the session launched.
`driverCloseMsg.streamName`	string	Virtual channel name.

driverInfo(msg)→ {Promise}

Callback that gets called for each session provided the virtual channel is enabled through the driverOpen callback. Use this to send any of the virtual channel information to the session.

Parameters

Name	Type	Description
`msg`	driverInfoMsg	Message from Session with session id and stream name.

Returns

Promise that is resolved with a driverInfoReply.

Type

Promise

Example

Example 1: Sending Ping count for the Ping VC

var counter = 3;
function pingDriverInfo(msg){
 return new Promise((resolve,reject)=>{
        var reply = {};
        reply["data"] = new Uint8Array(4);
        reply["length"] = 4;
        var offset =0;
        reply["offset"] = offset;
        offset = citrix.receiver.utils.writeUint16(reply["data"],offset,2048);
        offset = citrix.receiver.utils.writeUint16(reply["data"],offset,counter);
        resolve({"sessionId":msg["sessionId"], "streamName": msg["streamName"], "packet" :reply});
    }
});
<!--NeedCopy-->

Example 2: No data to be sent

function driverInfo(msg){
    return new Promise((resolve,reject)=>{ resolve({"sessionId":msg["sessionId"], "streamName": msg["streamName"],"packet":null})});
}
<!--NeedCopy-->

driverInfoMsg

Message received from session for driverOpen callback.

Type

Object

Properties

Name	Type	Description
`driverInfoMsg.sessionId`	string	Id of the session launched.
`driverInfoMsg.streamName`	string	Virtual channel name.

driverInfoReply

Reply to be sent by the driverInfo callback for each session.

Type

Object

Properties

Name	Type	Description
`driverInfoReply.sessionId`	string	Id of the session launched
`driverInfoReply.streamName`	string	Virtual channel name
`driverOpenReply.packet`	packet	Set the information in Uint8Array with offset and length appropriately or set null if no data to be sent.

driverOpen(msg)→ {Promise}

Callback that gets called when the virtual channel is about to be opened upon each session launch.

VC is enabled based on the driverOpenReply for each session.

Parameters

Name	Type	Description
`msg`	driverOpenMsg	Details of the session containing the session id and virtual channel name.

Returns

Promise that is resolved with a driverOpenReply.

Type

Promise

Example

//Driver Open callback for CTXPING virtual channel. You can handle any code initialization for this virtual channel for each session.
function pingDriverOpen(msg){
    //Enable/Disable the VC for the session with id = msg["sessionId"] by replying with enable flag true/false
    return new Promise((resolve , reject)=>{ resolve({"sessionId" : msg["sessionId"],"streamName":msg["streamName"],"enable":true});});;
}
<!--NeedCopy-->

driverOpenMsg

Contains the details of the session for which the driver is going to be opened.

Type

Object

Properties

Name	Type	Description
`driverOpenMsg.sessionId`	string	Id of the session launched.
`driverOpenMsg.streamName`	string	Virtual channel name.

driverOpenReply

Reply sent by the driverOpen callback for each session.

Type

Object

Properties

Name	Type	Description
`driverOpenReply.sessionId`	string	Id of the session launched
`driverOpenReply.streamName`	string	Virtual channel name
`driverOpenReply.enable`	boolean	Setting to true/false enables/disables the VC open for the session with id = `driverOpenMsg.sessionId`. By default, `driverOpenReply.enable` is set to false.

icaDataArrival(msg)

Callback that gets called when an ICA packet is sent by the server component of the virtual channel.

Should parse the packet received inside this callback.

Note:

Same callback is called when data arrives from any session launched for that virtual channel. Use sessionId to differentiate between the sessions.

Parameters

Name	Type	Description
`msg`	icaDataArrivalMsg	Details of the session containing the session id and virtual channel name.

Example

//Received packet from CTXPING virtual channel.

function pingIcaDataArrival(msg){
    var input = msg["packet"]["data"];
    var offset = msg["packet"]["offset"];
    var length = msg["packet"]["length"];

    var uSign = citrix.receiver.utils.readUint16(input,offset);
    offset +=2;
    var uType = citrix.receiver.utils.readUint16(input,offset);
    offset +=2;
    var uLen = citrix.receiver.utils.readUint16(input,offset);
    offset +=2;
    var uCounter = citrix.receiver.utils.readUint16(input,offset);
    offset +=2;
    var ulServerMS = citrix.receiver.utils.readUint32(input,offset);
    offset +=4;
    var ulClientMS = citrix.receiver.utils.readUint32(input,offset);
    offset +=4;

    //need to send reply here . Refer example for sendData for full implementation
}
<!--NeedCopy-->

icaDataArrivalMsg

Contains the details of the session and the ICA packet received.

Type

Object

Properties

Name	Type	Description
`icaDataArrivalMsg.sessionId`	string	Id of the session launched.
`icaDataArrivalMsg.streamName`	string	Virtual channel name.
`icaDataArrivalMsg.packet`	packet	ICA packet sent by the server side component of the virtual channel.

packet

Packet received/sent by session has the following format.

Type

Object

Properties

Name	Type	Description
`packet.data`	Uint8Array	Contains the data to be sent to the session or when received from the session. Refer here for more details on Uint8Array.
`packet.offset`	number	Offset from where the data needs to read/write from/to the Uint8Array (that is, `packet.data`).
`packet.length`	number	Length of the data to be read for that packet starting from the offset specified.

sendDataPacket

Data to be sent to the server has the following format.

Properties

Name	Type	Description
`sendDataPacket.sessionId`	String	id of the session.
`sendDataPacket.streamName`	String	Virtual channel name.
`sendDataPacket.packet`	packet	Packet format to be sent to server.

Window creation API definitions

createChildWindow

Creates a child window on top of the server host window. In the case of Citrix Workspace app for ChromeOS, the child window is a Webview. In the case of Citrix Workspace app for HTML5, the child window is an iFrame. By default, the child window is hidden.

Parameters

Name	Type	Description
`childWindowOptions`	object	Child Window configurations like Host ID of the corresponding server, Session ID

Returns

Returns an object containing the new child window properties ctxChildWindow.

Example

// Example 1 : Creation of a child window using main iFrame (useAppWindow)
let childWindowOptions = {
    hostID : "<host id>",    //Host ID of the corresponding server
    useAppWindow : true,  //Main window as child window
    sessionId : "1234567",   //Session ID
    bounds : {left:10, top:10, width:300, height:300} //Bounds for the new child window
}
let ctxChildWindow = citrix.receiver.window.createChildWindow(childWindowOptions);
ctxChildWindow.setBounds({left:10, top:10, width:300, height:300});
ctxChildWindow.setVisible(true);

// Example 2 : Creation of a child window as a new iFrame
let childWindowOptions = {
    hostID : "<host id>",    //Host ID of the corresponding server
    url : "https://127.0.0.1:8000/childwindow.html",
    useAppWindow : false,  //Main window as child window
    sessionId : "1234567",   //Session ID
    bounds : {left:10, top:10, width:300, height:300} //Bounds for the new child window
}
let ctxChildWindow = citrix.receiver.window.createChildWindow(childWindowOptions);
ctxChildWindow.setBounds({left:10, top:10, width:300, height:300});
ctxChildWindow.setVisible(true);
<!--NeedCopy-->

childWindowOptions

Contains the details of the session for which the virtual channel is used. It is essential to add the bounds parameter while creating the childWindow

Type

Object

Properties

Name	Type	Description
`childWindowOptions.hostID`	number	Corresponding server’s Host id.
`childWindowOptions.sessionId`	string	ID of the session launched.
`childWindowOptions.url`	string	Child Window will be created using this URL. Child Window will be a Webview/iFrame. Assigned to null if nothing is specified
`childWindowOptions.useAppWindow`	boolean	Use existing Main Child Window instead of creating new Child Window. In case the url is null, the useAppWindow must be true.
`childWindowOptions.bounds`	rect	Bounds

Rect

Contains the details of the co-ordinates for the childwindow created.

Type

Object

Properties

Name	Type	Description
`childWindowOptions.left`	number	Left co-ordinate of the rectangle.
`childWindowOptions.top`	number	Right co-ordinate of the rectangle.
`childWindowOptions.width`	number	Width of the rectangle.
`childWindowOptions.height`	number	Height of the rectangle.

CtxChildWindow~setBounds

Set Boundary to change the position and size of the Child Window.

Parameters

Name	Type	Description
`rect`	Rect	Boundary of the rectangle

Example

ctxChildWindow.setBounds(bounds);
<!--NeedCopy-->

CtxChildWindow~close

Close the Child Window.

Example

ctxChildWindow.close();
<!--NeedCopy-->

CtxChildWindow~setVisibleRects

Creates clipping regions that sets what part of the Child Window should be shown. Parts that are inside the regions are shown, while those outside are hidden. Note: Make sure to update transparent regions using setTransparentRegion whenever visible regions are changed.

Parameters

Name	Type	Description
`rect`	Rect	Boundary of the clip regions.
`rectType`	Rect	Type of the rect that is passed.

Example

//To Set Visible Regions with rectArray against session
ctxChildWindow.setVisibleRects([{left:10, top:10, width:300, height:300}, {left:100, top:700, width:300, height:300}], "rectRelativeToSession");
//To Set Visible Regions with rectArray against window
ctxChildWindow.setVisibleRects([{left:10, top:10, width:300, height:300}, {left:100, top:700, width:300, height:300}], "rectRelativeToWindow");
<!--NeedCopy-->

rectType

Contains the type of the rect that are passed for Rect.

Type

String - {‘rectRelativeToWindow’ ‘rectRelativeToSession’}

Properties

Name	Type	Description
`rectRelativeToWindow`	string	To set the region using Rect value against the window
`rectRelativeToSession`	string	To set the region using Rect value against the session

CtxChildWindow~setTransparentRegions

Creates regions that sets which part of the Child Window must be transparent. The transparent region is applied on top of the visible regions. Elements that are inside the region are hidden, while those outside are left unaffected.

Parameters

Name	Type	Description
`rect`	Rect	Boundary of the Transparent regions.
`rectType`	Rect	Type of the rect that is passed.

Example

//To Set Transparent Regions with rectArray against session
ctxChildWindow.setTransparentRegions([{left:700, top:10, width:300, height:300}, {left:700, top:700, width:300, height:300}], "rectRelativeToSession");
//To Set Transparent Regions with rectArray against window
ctxChildWindow.setTransparentRegions([{left:700, top:10, width:300, height:300}, {left:700, top:700, width:300, height:300}], "rectRelativeToWindow");
<!--NeedCopy-->

CtxChildWindow~setVisible

Toggle the visibility option to view or hide a Child Window.

Parameters

Name	Type	Description
`visibility`	boolean	To show/hide Child Window.

Example

ctxChildWindow.setVisible(true);
<!--NeedCopy-->

CtxChildWindow~setMouseClicksRegion

Creates regions that allows mouse events(mouse click /mouse up / mouse down/mouse move) to be sent to child window. Overrides the previously set region if any.

Parameters

Name	Type	Description
`rect`	Rect	Boundary of the Mouse event regions.
`rectType`	Rect	Type of the rect that is passed.

Example

//To Set Mouse Click Regions with rectArray against session
ctxChildWindow.setTransparentRegions([{left:10, top:10, width:300, height:300}, {left:100, top:700, width:300, height:300}], "rectRelativeToSession");
//To Set Mouse Click Regions with rectArray against window
ctxChildWindow.setTransparentRegions([{left:10, top:10, width:300, height:300}, {left:100, top:700, width:300, height:300}], "rectRelativeToWindow");
<!--NeedCopy-->

capabilities

Contains the list of capabilities that are available

Type

Object

Properties

Name	Type	Description
`windowManagement`	boolean	windowManagement capability supported
`monitorLayout`	boolean	monitorLayout capability supported

displayInfo

displayInfo options Array of Display details for each monitor

Type

ArrayObject

Properties

Name	Type	Description
`bounds`	Rect	windowManagement capability supported
`workArea`	Rect	monitorLayout capability supported

displayDetails

‘getMonitorDetails’ options

Type

Object

Properties

Name	Type	Description
`primaryMonitorID`	number	ID of Primary Monitor.
`displayInfo`	displayInfo	monitorLayout capability supported

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

global

March 6, 2024

Contributed by:

March 6, 2024

Contributed by: