SetScheduledActionCallback

Description

Sets up a callback function which will be called when a client application issues a scheduled action command.

[C++]
int SetActionCallback(void* context, ScheduledActionCallback callback);

   where ScheduledActionCallback type is defined as

    typedef int (*ScheduledActionCallback)(void* context, const ActionParameters* params);


Parameters [C/C++]

[in] void* context

Address of the context in which the callback function will be called.

[in] ScheduledActionCallback callback

Address of the callback function

[in] const ActionParameters* params

Pointer to an ActionParameters structure containing the following fields:

   unsigned int device_key
     The 32-bit value of the device key in the received action command.
   
   unsigned int group_key
     The 32-bit value of the group key in the received action command.
   

unsigned int group_mask

The 32-bit value of the group mask in the received action command.

unsigned __int64 action_time

The 64-bit value of the scheduled action time in nanoseconds.

Return Values

S_OK

Success

E_FAIL

Failure

Example

This fragment of an MFC code uses a scheduled action callback to set up an exact time for a frame trigger:

   bool onScheduledActionCommand(void* context, const ActionParameters* params)
      {
         CGigemuDlg* dlg = (CGigemuDlg*) context;
         return dlg->onActionCommand(params);
      }

bool CGigemuDlg::onScheduledActionCommand(const ActionParameters* params)

{

if((params.device_key==m_DeviceKey) && (params.group_key==m_GroupKey))

{

//action command is intended for our virtual camera, convert action time into windows file time

#define SEC_TO_UNIX_EPOCH 11644473600LL

#define WINDOWS_TICK 10000000

unsigned __int64 ll;

LPFILETIME pft;

ll = (params->action_time/1000000000 + SEC_TO_UNIX_EPOCH) * WINDOWS_TICK;

pft->dwLowDateTime = (DWORD)ll;

      pft->dwHighDateTime = (DWORD)(ll >> 32);

ScheduleTriggerTimer(pft);  //User-defined function for scheduling a frame transfer

return true;

}

//action parameters do not match action key settings of the virtual camera, ignore it

return false;

}

    bool CGigemuDlg::OnInitDialog()
      {

....

static CGevCamera* m_pCamera;

m_pCamera = createCamera();

m_pCamera->SetActionCount(1);

m_pCamera->SetScheduledActionCallback(this, &::onScheduledActionCommand);

....

}

Remarks

A scheduled action is used by a client application to trigger an action on the virtual camera at the specified time. Each scheduled action command contains a precise time for an action as well as information for the device to validate the requested operation: device key to authorize the action on this device, group key to define a group of devices on which actions have to be executed, and group mask to define different types of action. You should check these values from an incoming action command in the body of the ActionCommand callback and react to the action command accordingly. If the action command is ignored, your callback function must return False, otherwise it must return True. In the latter case GigESim will return an action acknowledge packet to the client application.

The scheduled_time is specified in the same time domain in which the internal GigESim timer operates. If the timer mode is set to UNIX time, scheduled_time should be interpreted as the amount of nanoseconds elapsed since 00:00:00 January 1, 1970. Otherwise it should be interpreted as the amount of nanoseconds elapsed since the execution of the current GigESim-based application or the last call to ResetTimer.

If you are using a callback function in the main thread of the simulation application, make sure that no lengthy processing is done in the body of the function as otherwise the connection to the remote client may become broken.