Overview
This article explains the usage of basic and advanced I/O functionality in exacqVision API (evAPI).
<br>
Usage
The network I/O functions provided in evAPI are required to send requests and receive responses from an exacqVision server. After initializing the API instance and connecting to a server, the I/O functions are necessary to maintain communication with the server. If functions such as EVAPI_Select, EVAPI_Send and EVAPI_Recv are not used, the API will not send or receive any data with the server.
When using evAPI network I/O in a multi-threaded environment, it is necessary to put a mutex around the network I/O functions and any other API function calls on a particular API instance. This ensures the integrity of the underlying read and write buffers. The mutex is not necessary for API function calls in the callback because the callback is executed from within EVAPI_Select and EVAPI_Read. See the advanced I/O example below for more information.
<br>
Basic Network I/O
The purpose of the basic network I/O functionality provided with evAPI is to enable the end user to send and receive data with an exacqVision server without worrying about the underlying network details.
Functions:
EVAPI_Select: initiates a send and receive on the underlying network socket. The timeout value is the maximum amount of time the function will block before returning, although generally the function will return sooner. This function needs to be called frequently to ensure the receipt and sending of data with the server.
EVAPI_SetTimeout: specifies the blocking timeout in milliseconds for EVAPI_Login, EVAPI_SearchCamera, and EVAPI_SearchCameraMulti.
EVAPI_CreateWindow (Windows only): creates a window with a window procedure that receives messages on socket status via WSAAsyncSelect and provides a drawing surface for subscribed video streams. The messages received on socket status act as an I/O pump and don’t require the use EVAPI_Select when subscribed to a video stream. To insure proper behavior, call this function right before subscribing to a video stream as in the window sample in the SDK. If there is a delay in calling EVAPI_CreateWindow and subscribing to a video stream, it will be necessary to call EVAPI_Select once to get the I/O pump started.
<br>
Example:
Function Main
Intialize evAPI (EVAPI_Init)
Connect to server (EVAPI_Connect)
// No need for select call when using the blocking login since it will be called // internally.
Login to server (EVAPI_Login)
While application running
// If EVAPI_Select is not called after the EVAPI_PTZGotoPreset, then
// the request will sit in the write buffer
Make request to server (EVAPI_PTZGotoPreset)
Perform network I/O (EVAPI_Select)
End while
End Function Main
<br>
Advanced Network I/O
The purpose of the advanced network I/O functions provided with evAPI is to allow greater control over sending and receiving on the network socket.
<br>
Functions:
EVAPI_GetSocket returns the socket that evAPI is using to send and receive data from the exacqVision server.
EVAPI_IsWriting returns the amount of data in the buffer to be written to the socket.
EVAPI_Recv calls socket function recv on the evAPI socket and reads the data into a buffer in the API instance. Execution of this function will result in parsing of the incoming data prior to the function returning. The callback will be executed for any relevant data.
EVAPI_Send calls socket function send on the evAPI socket and sends data in the write buffer of the API instance.
EVAPI_SetNonBlocking sets the blocking status of the I/O functions. This currently affects only EVAPI_Login.
<br>
Example:
Function evCallback(Parameters: ParamTypeparam, int value, Payload* payload, size_tlength )
Switch to handle ParamTypes
Case Login
Set login to true
End Case
Case Config
// Not necessary to mutex since there is a mutex around the read call
Make evAPI function call
End Case
End Switch
End Function evCallback
Function Main
Intialize evAPI (EVAPI_Init)
Set callback to Function evCallback (EVAPI_SetCallback)
Set to non-blocking (EVAPI_SetNonBlocking)
Connect to server (EVAPI_Connect)
Login to server (EVAPI_Login)
// If EVAPI_Select is not called after the EVAPI_Login, then the
// request will sit in the write buffer
Perform network I/0 (EVAPI_Select)
// Have to wait for the login to succeed or for a timeout before continuing
While not login or not timeout
End While
If not login
Goto End Function Main
End if
Spawn I/O Thread
While application running
Lock mutex
Call an evAPI function
Unlock mutex
End while
End Function Main
I/O Thread
Create empty read set of sockets (fd_set read)
Create empty write set of sockets (fd_set write)
Get underlying API socket (EVAPI_GetSocket)
While thread running
If there is data in the write buffer (EVAPI_IsWriting)
Add the socket to the write set (FD_SET)
End if
// Always add the socket to the read set
Add the socket to the read set (FD_SET)
Check to see if socket is ready to read and/or write (select)
If the socket is in the write set (FD_ISSET)
Lock mutex
Write the data (EVAPI_Write)
Unlock mutex
End if
If the socket is in the read set (FD_ISSET)
Lock mutex
Read the data (EVAPI_Read)
Unlock mutex
End if
End while
End I/O Thread
<br>
How-to-Using-exacqVision-API-Network-IO.pdf
