Programming reference
For function summaries, see:
canLoad
Determines whether this driver can be loaded without error. It is the first remote call in the receiver.
Calling convention
boolean canLoad();
<!--NeedCopy-->
Parameters
None
Return values
If the virtual driver is ready to work, the returned value is true. If it is not, the returned value is false.
Remarks
When this method returns the value false, the virtual channel for this virtual driver cannot be created. That means that the virtual driver cannot work in the ICA session.
getDisplayName
Returns the display name of the virtual channel and sends it to the server.
Calling convention
String getDisplayName();
<!--NeedCopy-->
Parameters
None
Return values
Returns display name of virtual channel as a String.
Remarks
Display name is a friendly name of the virtual channel, used to report errors.
getMinVersionNumber
Returns minVersion, the lowest supported version of this virtual channel, used to allow version
negotiation between the client-side and the server-side components.
Calling convention
int getMinVersionNumber();
<!--NeedCopy-->
Parameters
None
Return values
The lowest supported version of this virtual channel.
Remarks
For more information on which virtual channel version to use, please see Design suggestions.
getMaxVersionNumber
Returns maxVersion, the highest supported version of the virtual channel, used to allow version
negotiation between the client-side and the server-side components.
Calling convention
int getMaxVersionNumber();
<!--NeedCopy-->
Parameters
None
Return values
The highest supported version of this virtual channel.
Remarks
For more information on which virtual channel version to use, please see Design suggestions.
getVCName
Returns the virtual channel name, sent to identify the virtual channel to the server.
Calling convention
String getVCName();
<!--NeedCopy-->
Parameters
None
Return values
Returns the virtual channel name.
Remarks
Each virtual channel has a unique name to identify itself. For more information, see Naming virtual channels.
initializeDriver
This method is for service to carry out initialization work before the virtual channel starts.
Calling convention
boolean initializeDriver ();
<!--NeedCopy-->
Parameters
None
Return values
Returns a Boolean value showing the status of initialization. If initialization is successful, this method returns the value true. If unsuccessful, this method returns the value false.
Remarks
If this method returns false, a virtual channel for this method cannot be created.
getDriverInfo
When an ICA session starts, it calls this method to retrieve module-specific information for transmission to the server. This information returns to the server side of the virtual channel by WFVirtualChannelQuery().
Calling convention
byte[] getDriverInfo();
<!--NeedCopy-->
Parameters
None
Return values
Returns byte[], the output byte array to be sent to the server.
Remarks
driverStart
Called when the virtual driver is started by the Citrix Workspace app for Android.
Calling convention
void driverStart(in IVCCallback cb);
<!--NeedCopy-->
Parameters
-
cb
The callback provided to the virtual driver service.
Return values
None
Remarks
The instance of IVCCallback is passed to the virtual driver in this method. Citrix recommends to not call sendData in driverStart. The callbacks must be used after driverStart returns.
icaDataArrival
This method is called repeatedly when the virtual driver is running. The implementation must read command bytes from its vStream byte array and process them accordingly.
Calling convention
void icaDataArrival(in byte[] vStream);
<!--NeedCopy-->
Parameters
-
vStream
The byte array used to read data from the server component of the virtual channel.
Return values
None
Remarks
As Citrix Workspace app for Android does not know any package detail, it only transfers all available data from ICA stream to the virtual driver by calling this method. If the virtual channel package is too large, the whole package may not arrive at the same time. That means the implementation of this method must be able to handle partial packages. See Ping, Over and Mix sample codes, which provide examples about how to handle partial packages.
If the server application sends several packages continuously, more than one package may come in the same byte array. Thus, the implementation of this method must be able to handle more than one package in the array. See Over and Mix sample codes, which provide examples for handling more than one package in one byte array. For the Ping sample, the server application sends data synchronously. The server waits for the client to reply before sending the next packet, so the Ping sample doesn’t need to handle this scenario.
driverShutdown
Called when the virtual channel is shut down by Citrix Workspace app for Android.
Calling convention
void driverShutdown();
<!--NeedCopy-->
Parameters
None
Return values
None
Remarks
This method is to inform the virtual driver that the virtual channel closes. Once the virtual channel closes, data cannot be sent to the server. Citrix Workspace app for Android waits for confirmation after calling this
method. If virtual driver doesn’t call confirmShutdown() to confirm in time, the virtual channel stays closed.
sendData
To send a package of channel protocol to the server.
Calling convention
void sendData(in byte[] data, in int off, in int length);
<!--NeedCopy-->
Parameters
-
data
The data as byte array to be sent to the server side.
-
off
The start offset in the data array.
-
length
The number of bytes to send.
Return values
None
Remarks
This method must be used after driverStart returns and before driverShutdown is called.
confirmShutdown
Called to confirm that the virtual channel can be shut down. It must be called after driverShutdown() is called. Once confirmed, any data sent to the server component is ignored.
Calling convention
void confirmShutdown();
<!--NeedCopy-->
Parameters
None
Return values
None
Remarks
To make sure that all data sent from the Client has finished and it is safe to terminate the channel. This method must be called after driverShutdown is called. When driverShutdown is called, Citrix Workspace app
for Android waits for confirmation. Virtual driver can call confirmShutdown to confirm that the virtual channel can be closed. If this method is not called in time, the virtual channel stays closed.
writeInt2
Writes an int to a buffer in the form of two bytes, little endian order.
Calling convention
int writeInt2(byte[] buffer, int offset, int i)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to write the integer to.
-
offset
Offset from the start of the buffer, where this method starts writing the int.
-
i
The int to write.
Return values
Returns offset + 2.
Remarks
writeInt4
Writes an int to a buffer in the form of four bytes, little endian order.
Calling convention
int writeInt4(byte[] buffer, int offset, int i)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to write the integer to.
-
offset
Offset from the start of the buffer, where this method starts writing the int.
-
i
The int to write.
Return values
Returns offset + 4.
Remarks
writeInt2
Writes an int to an output stream in the form of two bytes, little endian order.
Calling convention
void writeInt2(ByteArrayOutputStream stream, int i)
<!--NeedCopy-->
Parameters
-
stream
The stream to write the integer to.
-
i
The int to write.
Return values
Remarks
writeInt4
Writes an int to an output stream in the form of four bytes, little endian order.
Calling convention
void writeInt4(ByteArrayOutputStream stream, int i)
<!--NeedCopy-->
Parameters
-
stream
The stream to write the integer to.
-
i
The int to write.
Return values
Remarks
readInt2
Reads two bytes from a byte array in little endian order and creates a two bytes short.
Calling convention
short readInt2(byte[] buffer, int index)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to read the short integer from.
-
offset
Offset from the start of the buffer, where this method starts reading the short integer.
Return values
Returns the short integer.
Remarks
readInt4
Reads four bytes from a byte array in little endian order and creates a four byte integer.
Calling convention
int readInt4(byte[] buffer, int index)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to read the integer from.
-
offset
Offset from the start of the buffer, where this method starts reading the integer.
Return values
Returns the integer.
Remarks
readUInt2
Reads two bytes from a byte array in little endian order and creates an unsigned value stored in an integer.
Calling convention
int readUInt2(byte[] buffer, int index)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to read the unsigned integer from.
-
offset
Offset from the start of the buffer, where this method starts reading the unsigned integer.
Return values
Returns the unsigned integer.
Remarks
readUInt1
Reads one byte from a byte array in little endian order and creates an unsigned value stored in an integer.
Calling convention
int readUInt1(byte[] buffer, int index)
<!--NeedCopy-->
Parameters
-
buffer
The buffer to read the unsigned integer from.
-
offset
Offset from the start of the buffer, where this method starts reading the unsigned integer.
Return values
Returns the unsigned integer.