SetScheduledActionCallback
Top  Previous  Next

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.