Assist API

Acquire Assist comes as a stand alone EXE AcquireAssist.exe which must be configured prior to use using the following file format:

See: Config File Configuration (Standalone)

To interact with the API use the following:

// CopyData Message ID
#define ASSIST_ID				  0x101



// Notification message IDs (WPARAM) - value/description in LPARAM
#define ASSIST_NOTIFY_VIDEOMUTE    5   // 2.0.0.11 onwards
#define ASSIST_NOTIFY_AUDIOMUTE    4   // 2.0.0.11 onwards
#define ASSIST_NOTIFY_NUMOPERATORS 3   // 2.0.0.11 onwards
#define ASSIST_NOTIFY_PLAYRINGTONE 2
#define ASSIST_NOTIFY_STATUSCHANGE 1



// Windows messages to use
#define WM_ASSIST_SUBSCRIBE      (WM_APP+20)
#define WM_ASSIST_UNSUBSCRIBE    (WM_APP+21)
#define WM_ASSIST_REQUESTHELP    (WM_APP+22)
#define WM_ASSIST_CANCELHELP     (WM_APP+23)
#define WM_ASSIST_QUERYSTATUS    (WM_APP+24)
#define WM_ASSIST_SILENTMODE     (WM_APP+25)
#define WM_ASSIST_REQUESTFRAME   (WM_APP+26)    // 2.0.0.11 onwards
#define WM_ASSIST_ACCEPTCALL     (WM_APP+27)    // 2.0.0.12 onwards
#define WM_ASSIST_REJECTCALL     (WM_APP+28)    // 2.0.0.12 onwards



// Formats supported - 2.0.0.11 onwards
#define ASSIST_FORMAT_NV12        0x01
#define ASSIST_FORMAT_YV12        0x02
#define ASSIST_FORMAT_I420        0x04
#define ASSIST_FORMAT_UYVY        0x08
#define ASSIST_FORMAT_YUY2        0x10

#define ASSIST_VIDEO_SECONDFEED   0x80


// The response to any SendMessage command
#define ASSIST_RESULT_OK         1
#define ASSIST_RESULT_ERROR      0


// Credentials Data Block
#pragma pack(1)
struct AssistCredentials {
	char username[128];
	char password[128];
	char kioskName[128];

	char audioMuteGraphic[MAX_PATH];
	char cameraPauseGraphic[MAX_PATH];
};
#pragma pack()



// Different States
enum AssistStatus
{
		  asReady            = 0    // Logged in and waiting to be used
		, asDialling         = 1    // Dialing (looking for operator)
		, asConnecting       = 2    // Operator answered, connecting
		, asUnavailable      = 3    // Network error/bad credentials
		, asTempUnavailable  = 4    // No operators available
		, asInCall           = 5    // Now in active call
    , asIncommingCall    = 6    // Incoming call to the kiosk
	  , asErrorNotAvailable= 0xff // only returned if an error occurs
};



enum VideoWindowStatus 
{ 
		vwsHidden           = 0,     // Video should be hidden
		vwsNoVideo          = 1,     // Call has no video right now (muted)
		vwsVideo            = 2      // Call has video (unmuted)
};

To locate the Assist application perform the following:

HWND hwndAssistControl = FindWindow(L"AcquireAssistAPI",L"AcquireAssistAPI");

Once located you can then send the following to subscribe to notifications from assist

SendMessage(hwndAssistControl, WM_ASSIST_SUBSCRIBE, <your_window_handle>, <message_to_use>)

To unsubscribe from notifications:

SendMessage(hwndAssistControl, WM_ASSIST_UNSUBSCRIBE, <your_window_handle>, 0)

Assist will post messages to the window handle you provide using the message you specify with the following meanings:

Before Assist will do anything you need to provide server login credentials using the following code:

// WM_COPYDATA Structure
COPYDATASTRUCT copyDataInitAssist;
// Assist credentials
AssistCredentials assistCredentials;
// Prepare the structure
copyDataInitAssist.lpData = &assistCredentials;
copyDataInitAssist.cbData = sizeof(assistCredentials);
copyDataInitAssist.dwData = ASSIST_ID;



// Setup the credentials
strcpy_s(assistCredentials.username,"test4");
strcpy_s(assistCredentials.password,"test4");
strcpy_s(assistCredentials.kioskName, "Test Unit");
strcpy_s(assistCredentials.audioMuteGraphic, "mute.bmp");
strcpy_s(assistCredentials.cameraPauseGraphic, "novideo.bmp");
SendMessage(hwndAssistControl, WM_COPYDATA, (WPARAM)hWnd, (LPARAM)&copyDataInitAssist);

To request help send:

SendMessage(hwndAssistControl, WM_ASSIST_REQUESTHELP, 0, 0)

To cancel the request or hand up the call send:

SendMessage(hwndAssistControl, WM_ASSIST_CANCELHELP, 0, 0)

At any point you can call the following to find out the current status. Note AssistStatus::asErrorNotAvailable will result if you haven't supplied any credentials yet or for some reason it isn't running internally.

AssistStatus status = (AssistStatus)SendMessage(hwndAssistControl,WM_ASSIST_QUERYSTATUS,0,0)

Silent Mode

Silent mode allows you to disable all windows that appear from Assist and the raw video data is re-directed to a window you specify allowing you to control and draw everything.

This is supported from API version 2.0.0.11

To enable silent mode, you do the following:

SendMessage(hwndAssistControl, WM_ASSIST_SILENTMODE, <window handle>, <supported formats>)

Where:

<window handle> is a handle to a window that will receive the video data.

<supported formats> is a bit-mask using the ASSIST_FORMAT_ defines specifying which output formats that you can support. The system will choose the best match.

Calling the above with the <window handle> = 0 will disable silent mode. If will stay in silent mode until the API is restarted or until you send the above message.

To ask Assist to send you a video frame:

SendMessage(hwndAssistControl, WM_ASSIST_REQUESTFRAME, 0, 0)

And one will be sent next time it is received. It will keep sending frames until you return '1' in the WM_COPYDATA message (see below)

When a video frame is ready it will be sent as follows:

When a video frame is ready it will be sent as follows:

WM_COPYDATA

Your application must be able to process and respond to this within 50ms. It is advised that you copy the buffer for processing elsewhere.

In the COPYDATASTRUCT:

• • dwData: will be set to one of the video formats to identify the format in use. Note: you need to take this value and AND it with 0x7F. It is possible that the M.S.B. (ASSIST_VIDEO_SECONDFEED) may be set, and if it is then this represents a secondary feed which may contain some sort of accessibility video feed)
  • cbData: Size of the raw video data + 2 longs for width and height (see below)
  • lpData: Pointer to the video data, which is formatted as:

    • long width

      long height

      raw video data

• You must return a value to this function.
  0: An error occurred (Assist will retry at the next frame)
  1: frame received OK (don't send another yet)

 Any other value: (Frame received OK, and ready for another)