SetActionCallback
Top  Previous  Next

Description

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

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

   where ActionCallback type is defined as

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


Parameters [C/C++]
 
[in] void* context  
Address of the context in which the callback function will be called.  
 
[in] ActionCallback 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.   
Return Values

S_OK  
Success  
E_FAIL  
Failure  


Example

This fragment of an MFC code uses an action callback to validate the action command, determine what type of action is requested and implement it.

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

bool CGigemuDlg::onActionCommand(const ActionParameters* params)  
{  
  if((params.device_key==m_DeviceKey) && (params.group_key==m_GroupKey))  
  {  
    //action command is intended for our virtual camera, implement corresponding action and return true  
       if(params.group_mask & 1))  
    {  
         ImplementAction1();  
         return true;  
    }  
       else if(params.group_mask & 2))  
    {  
         ImplementAction2();  
         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->SetActionCallback(this, &::onActionCommand);  
       ....  
}  
 

Remarks

Action commands are used by a client application to trigger a simultaneous action on multiple devices at roughly the same time. Each action command contains 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.

To receive schedule action commands, use SetScheduledActionCallback.

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.