QAWeb Integration API

User’s Guide

Barco n.v.
[Link]
K5902021-05

BARCO – Healthcare Division

Pres. Kennedypark 35
B-8500 Kortrijk, Belgium
Tel.: +32 56 233 211 - Fax: +32 56 233 457
11/May/17 QAWeb Integration API User Guide

Table of contents

Table of contents ................................................................................................................ 2

Introduction ........................................................................................................................ 3
Summary ......................................................................................................................... 3
API overview................................................................................................................... 3
Requirements ................................................................................................................. 3
File components ............................................................................................................. 3
Sample application ............................................................................................................. 4
The API functions ................................................................................................................ 7
INT GetGlobalStatus (INT * nStatus, LPWSTR szwBuffer, INT * nBufferSize) ........... 7
INT GetPendingActionList(LPWSTR szwBuffer, INT * nBufferSize) ........................... 7
void WaitForUpdate() ................................................................................................. 8
INT BrowseServer() .................................................................................................... 8
INT StartAgent().......................................................................................................... 8
INT ILuminateOn() ...................................................................................................... 9
INT ILuminateOff() ...................................................................................................... 9
INT SwitchTargetForAllCSDFDisplays (LPSTR szChroma, LPSTR szLuminance, LPSTR
szAmbient, int csdf, bool createICCProfile) ............................................................... 9
INT GetSwitchTargetStatus() .................................................................................... 10

2
11/May/17 QAWeb Integration API User Guide

Introduction

Summary
This document provides information to assist application developers to integrate QAWeb in a
proprietary application, (such as a PACS viewing application) or desktop.

API overview
The API is a set of C-functions, exported by a DLL, named [Link].
The API provides support for the following tasks:
• Obtaining the current workstation’s status (OK or NOT OK)
• Obtaining the list of failed actions, in case of a NOT OK status
• Obtaining the list of pending actions (= actions that require manual interaction and need to
be started manually from the QAWeb Agent).
• Launching QAWeb Agent.
• Launching the QAWeb Server in the default browser.
• Enabling and disabling the I-Luminate functionality on supported displays
• Switching the calibration target asynchronously (for CSDF supporting displays)

Requirements
• QAWeb Agent must be installed.
• The [Link] must correspond to the installed QAWeb (i.e. the one that was
copied to the “QAWeb API” folder during QAWeb installation).
• The [Link] can be copied to and used from any location on the hard disk.

File components
• [Link]: the dynamic link library, that exports all functions described below
• qaweb-integration.h: the include files, that holds all function declarations
• [Link]: the import library to link to [Link]
The DLL may also be explicitly loaded at run-time, by using the LoadLibrary and GetProcAddress
Windows API function. In this context, it may be useful to note that all functions use the __cdecl
calling convention and C linkage. As a consequence, the exported function names are not decorated.

3
11/May/17 QAWeb Integration API User Guide

Sample application

#include <windows.h>
#include <stdio.h>
#include "qaweb-integration.h"

#define _REPLACE_TABS_BY_NEWLINES(wszBuffer) \
for (int i = 0 ; wszBuffer[i] != (wchar_t)'\0' ; i ++) \
if (wszBuffer[i] == (wchar_t)'\t') wszBuffer[i] = (wchar_t)'\n' ;
#define _PRINT_UNEXPECTED_ERROR printf("An unexpected error has
occured\n") ;

int main(int argc, char* argv[])

{
int action ;
INT retval ;

while (true)
{
printf("Menu options:\n\
- Get status + failed actions (s)\n\
- Get pending actions (p)\n\
- Start Agent(a)\n- Browse Server (b)\n\
- Wait for an update (w)\n\
- Exit (e)\nEnter option [s]: ");
fflush(stdout);
fflush(stdin);
action = getc(stdin);
if (action == (char)'e')
{
return 0;
}

printf("\n");

switch (action)
{
case (char)'p':
{
INT nBufferSize ;
retval = GetPendingActionList(NULL, &nBufferSize);
if (retval == QAWEBINTEGRATION_SUCCESS)
{
printf("There are no pending actions\n") ;
}
else if (retval == QAWEBINTEGRATION_BUFFER_TOO_SMALL)
{
wchar_t * szBuffer = (wchar_t *)malloc(nBufferSize * 2) ;
retval = GetPendingActionList(szBuffer, &nBufferSize);
if (retval == QAWEBINTEGRATION_SUCCESS)
{
_REPLACE_TABS_BY_NEWLINES(szBuffer);
wprintf(L"Pending actions:\n%s\n", szBuffer) ;

4
11/May/17 QAWeb Integration API User Guide

}
else
{
_PRINT_UNEXPECTED_ERROR;
}
free(szBuffer) ;
}
else
{
_PRINT_UNEXPECTED_ERROR;
}
break;
}
case (char)'a':
{
retval = StartAgent() ;
if (retval == QAWEBINTEGRATION_SUCCESS)
{
printf("QAWeb Agent is started.\n");
}
else
{
_PRINT_UNEXPECTED_ERROR
}
break;
}
case (char)'b':
{
retval = BrowseServer() ;
if (retval == QAWEBINTEGRATION_SUCCESS)
{
printf("Server page is opended in default browser.\n");
}
else
{
_PRINT_UNEXPECTED_ERROR
}
break;
}
case (char)'w':
{
printf("Waiting till QAWeb updates shared information...\n");
WaitForUpdate() ;
printf("Shared information has been updated.\n");
break;
}
default:
{ // status
INT nBufferSize ;
INT nStatus ;
retval = GetGlobalStatus(&nStatus, NULL, &nBufferSize);
if (retval == QAWEBINTEGRATION_SUCCESS)
{
printf("Status = %s\n", nStatus == 0? "OK" : "NOT OK") ;
printf("There are no failed actions\n") ;
}
else if (retval == QAWEBINTEGRATION_BUFFER_TOO_SMALL)

5
11/May/17 QAWeb Integration API User Guide

{
wchar_t * szBuffer = (wchar_t *)malloc(nBufferSize * 2) ;
retval = GetGlobalStatus(&nStatus, szBuffer, &nBufferSize);
if (retval == QAWEBINTEGRATION_SUCCESS)
{
printf("Status = %s\n", nStatus == 0? "OK" : "NOT OK") ;
_REPLACE_TABS_BY_NEWLINES(szBuffer);
wprintf(L"Failed actions:\n%s\n", szBuffer) ;
}
else
{
_PRINT_UNEXPECTED_ERROR;
}
free(szBuffer) ;
}
else
{
_PRINT_UNEXPECTED_ERROR;
}
break;
}
}

printf("\n");
}
}

This is a simple console application that demonstrates the usage of all API functions:

Each item in the menu corresponds to an API functionality.

6
11/May/17 QAWeb Integration API User Guide

The API functions

INT GetGlobalStatus (INT * nStatus, LPWSTR szwBuffer, INT * nBufferSize)
This function retrieves the workstation’s current global status plus a list of all actions that have failed.
Parameters:
• nStatus [out]: a memory address of an integer that will contain as output the current
workstation status: 0 = OK, 1 = NOT OK, 2 = UNKNOWN
Status UNKNOWN means that QAWeb hasn't retrieved the actual workstation state yet.
QAWeb is only for a short period in this state, typically after having installed QAWeb Agent
and after having started up the system.
• szwBufferr [in/out]: an address to data memory in which the list of all failed actions will be
written as output. The list is a TAB delimited, zero-terminated Unicode string.
For actions that are display dependent, also the display in question is mentioned: e.g.
“Compliance Test on Barco E-3632, 1876001423”.
This string is localized (= translated according to the current locale): currently, only Japanese
and French are supported.
To retrieve only the required memory size, the function should be called with szwBuffer set
to NULL input.
• nBufferSize [in/out]: memory address of an integer that holds the allocated memory size in
words (= Unicode characters) for swzBuffer as input.
If more memory is required or if szwBuffer is NULL, the referred integer will contain as
output the minimum required size in words, nothing will be written to szwBuffer, and the
function will return QAWEBINTEGRATION_BUFFER_TOO_SMALL.
Return values:
• QAWEBINTEGRATION_SUCCESS upon success.
• QAWEBINTEGRATION_BUFFER_TOO_SMALL more memory needs to be allocated to hold the list
of failed actions or szwBuffer is NULL.
• QAWEBINTEGRATION_UNEXPECTED_ERROR in case of a failure.
Remark:
If there are no failed actions, nothing needs to be written to the output buffer (szwBuffer). In this
case the function will return QAWEBINTEGRATION_SUCCESS and set *nBufferSize to zero if no out-
put buffer was provided (szwBuffer == NULL), or write a zero length string to the output buffer if
enough memory was allocated to hold at least one (unicode) character (*nBufferSize > 0).

INT GetPendingActionList(LPWSTR szwBuffer, INT * nBufferSize)

This function retrieves the list of all pending actions (= actions that require manual interaction, and
should be started manually from the QAWeb Agent).
Parameters:
• szwBufferr [in/out]: an address to data memory in which the list of all pending actions will
be written. The list is a TAB delimited, zero-terminated Unicode string.
For actions that are display dependent, also the display in question is mentioned: e.g.
“Compliance Test on Barco E-3632, 1876001423”.
This string is localized (= translated according to the current locale): currently, only Japanese

7
11/May/17 QAWeb Integration API User Guide

and French are supported.

To retrieve only the required memory size, the function should be called with szwBuffer set
to NULL as input.
• nBufferSize [in/out]: memory address of an integer that holds the allocated memory size in
words (= Unicode characters) for swzBuffer as input.
If more memory is required or if szwBuffer is NULL, the referred integer will contain as
output the minimum required size in words, nothing will be written to szwBuffer, and the
function will return QAWEBINTEGRATION_BUFFER_TOO_SMALL.
Return values:
• QAWEBINTEGRATION_SUCCESS upon success.
• QAWEBINTEGRATION_BUFFER_TOO_SMALL more memory needs to be allocated to hold the list
of failed actions or szwBuffer is NULL.
• QAWEBINTEGRATION_UNEXPECTED_ERROR in case of a failure.
Remark:
If there are no pending actions, nothing needs to be written to the output buffer (szwBuffer). In
this case the function will return QAWEBINTEGRATION_SUCCESS and set *nBufferSize to zero if no
output buffer was provided (szwBuffer == NULL), or write a zero length string to the output buf-
fer if enough memory was allocated to hold at least one (unicode) character (*nBufferSize > 0).

void WaitForUpdate()
This function returns when QAWeb Agent has updated the information that is returned by one of
previous functions. This does not necessarily mean that the content (= the information itself) has
changed: it is up to the application to handle this, if required.

INT BrowseServer()
This function launches the QAWeb Server application in the default browser and opens directly the link
to the workstation:
• if the Agent is not registered yet, [Link] is opened in the
browser).
• if the Agent is waiting for acceptance on the server, the facility page opens in the default
browser.
• if the Agent is registered on the server, the workstation page opens in the default browser.
Return values:
• QAWEBINTEGRATION_SUCCESS upon success.
• QAWEBINTEGRATION_UNEXPECTED_ERROR in case of a failure.

INT StartAgent()
This function starts QAWeb Agent
Return values:
• QAWEBINTEGRATION_SUCCESS upon success.

8
11/May/17 QAWeb Integration API User Guide

• QAWEBINTEGRATION_UNEXPECTED_ERROR in case QAWeb Agent could not be started, due to

one or another unexpected error.

INT ILuminateOn()
This function sets the active viewing mode to "I-Luminate" on all displays that support the I-Luminate
functionality.
Return value:
• Always returns QAWEBINTEGRATION_SUCCESS
Notes:
• This function will interrupt and delay any QAWeb action that is running in the background at
that time.
• The display automatically returns to its original viewing mode after a short while (typically
one minute).
• This function has no effect on displays that were already in "I-Luminate" mode.

INT ILuminateOff()
This function sets the active viewing mode to "Diagnostic" on all displays that support the I-Luminate
functionality.
Return value:
• Always returns QAWEBINTEGRATION_SUCCESS
Notes:
• This function has no effect on displays that were already in "Diagnostic" mode.

INT SwitchTargetForAllCSDFDisplays (LPSTR szChroma, LPSTR szLuminance, LPSTR szAmbient, int

csdf, bool createICCProfile)
This function asynchronously switches the calibration target for all displays that support the
SteadyColor Calibration (i.e. the displays that have a 3D LUT, such as the Uniti display). If you switch to
a target for which the display was never calibrated before, the display will be calibrated. If however,
you switch to a target that has been calibration already before, the corresponding (display) settings
are restored without performing a new calibration.
Parameters:
• szChroma [in]: a zero terminated string, specifying the new target chroma. This should be
one of following strings (without the quotes): "NATIVE_WHITE", "BLUEBASE" or "CLEARBASE".
• szLuminance [in]: a zero terminated string, specifying the new target luminance. This should
be either a number in case of an absolute luminance (unit = cd/m2) or one of following
strings (without the quotes): "MAXIMUM_LIFETIME" or "MAXIMUM_LUMINANCE".
• szAmbient [in]: a zero terminated string, specifying the ambient light condition. This should
be one of following strings (without the quotes): "DARK_ROOM",
"XRAY_DIAGNOSTIC_READING_ROOM", "CT_MR_NM_READING_ROOM" ,"STAFF_OFFICE",
"CLINICAL_VIEWING_ROOM" , "ER_ROOM" or "OR_ROOM".
• csdf [in]: an integer, specifying if SteadyColor Calibration should be enabled. Following
numbers can be used:

9
11/May/17 QAWeb Integration API User Guide

o 0 = disable SteadyColor Calibration

o 1 = enable SteadyColor Calibration with Standard method
o 2 = enable SteadyColor Calibration with Full CSDF method
• createICCProfile [in]: a boolean that specifies whether or not an ICC profile has to be created
and associated with the display. This parameter is ignored if SteadyColor Calibration has to be
disabled (see csdf parameter)
Return values:
• QAWEBINTEGRATION_SUCCESS upon success.
• QAWEBINTEGRATION_ERROR_REGISTERED if the QAWeb Agent is registered on the server, and
hence this functionality is not available
• QAWEBINTEGRATION_ERROR_INVALID_PARAMETER if one of the input parameters holds an
invalid value
• QAWEBINTEGRATION_ERROR_TARGETSWITCH_INPROGRESS if a calibration target switch is
already in progress. In this case the requested target switch will not be executed.

Notes:
• The target display function cannot be specified, and is always DICOM.
• This function is asynchronously, meaning that the function immediately returns while the
switch is performed in a background process (by QAWeb Agent). Keep in mind that switching
the calibration target may take several minutes (depending on the fact whether a new
calibration needs to take place or not).
• The target can only be switched on a standalone Agent. If the Agent is registered, the
function will return QAWEBINTEGRATION_ERROR_REGISTERED, and nothing will happen.
• Make sure that the Agent (GUI) is not open when you execute this function: in this case, the
switch will only actually start after the Agent is closed.
• If a calibration is required, the display will be calibrated in FAST mode. If you want to do a
FULL calibration instead, you should start a calibration from the Agent GUI. QAWeb Agent
keeps only the settings from the most recent calibration (per given target and display).
• Calibration data is only valid till the next Auto-Calibration. At that time, the display(s) will be
automatically re-calibrated for the current target, and upon switching for the other targets.

INT GetSwitchTargetStatus()
This function returns the status of the last calibration target switch that was initiated by a call to the
asynchronous SwitchTargetForAllCSDFDisplays() function.
Return values:
• QAWEBINTEGRATION_TARGETSWITCH_INPROGRESS: the target switch is still in progress
• QAWEBINTEGRATION_TARGETSWITCH_FINISHED: the target switch is finished
• QAWEBINTEGRATION_TARGETSWITCH_FAILED: the target switch has failed

10