IDS Software Suite 4.96.1

Syntax

INT is_Multicast(HIDS hCam, UINT nCommand, void* pParam, UINT cbSizeOfParams)

Description

With this function you configure the multicast mode of a GigE uEye camera or open a virtual multicast camera. The camera itself must be opened by the master PC to be additionally available as a virtual multicast camera. Only then the virtual multicast camera is free and available for other client PCs.

The commands are divided as active and passive multicast commands. Active commands changes parameters in the camera. For this purpose the camera must be available (but not opened) and device ID must be used in the camera handle. Passive multicast commands are used to open a virtual multicast camera by a client in read-only mode.

For multicast mode, you must configure the camera with a persistent IP address (is_IpConfig()) and a multicast IP adress. Valid multicast IP addresses are from 224.0.0.1 to 239.255.255.255. However, the address range 224.0.0.0 to 224.0.0.255, inclusive, is reserved for use by routing protocols and other low-level topology determination or maintenance protocols.

The following restrictions apply to multicast cameras:

•The persistent IP address of the GigE uEye camera must be in the subnet of the network adapter. Possible clients of the virtual multicast camera must also be in this subnet.

•If the master changes the camera settings, these changes also apply on the image of the clients. The clients can only change camera-independent functions (e. g. software gamma or software LUT).

•The software hot pixel correction does not work on client PCs.

•If multicast mode is enabled (IS_PMC_CMD_INITIALIZE), this may affect the performance of the API application.

The nCommand input parameter is used to select the function mode. The pParam input parameter depends on the selected function mode. If you select functions for setting or returning a value, pParam contains a pointer to a variable of the UINT type. The size of the memory area to which pParam refers is specified in the cbSizeOfParam input parameter.

Input parameters

Content of the IS_PMC_READONLYDEVICEDESCRIPTOR structure

Return values

Example 1

/* Check if the passive multicast mode is enabled for the entire system. */
BOOL enable = FALSE;
int nRet = is_Multicast(0, IS_PMC_CMD_SYSTEM_GET_ENABLE, &enable, sizeof(enable));
 
if(nRet == IS_SUCCESS)
{
if(enable == TRUE)
{
  /* Initialize multicast mode in local API instance. */
  nRet = is_Multicast(0, IS_PMC_CMD_INITIALIZE, NULL, 0);
  if(nRet == IS_SUCCESS)
  {
    /* Load all multicast devices from the system configuration. */
    nRet = is_Multicast(0, IS_PMC_CMD_LOADDEVICES, NULL, 0);
  }
}
}

Example 2

IS_PMC_READONLYDEVICEDESCRIPTOR roDeviceDescriptor;
 
/* Set camera IP to 192.168.0.100 */
roDeviceDescriptor.ipCamera.by.by1 = 192;
roDeviceDescriptor.ipCamera.by.by2 = 168;
roDeviceDescriptor.ipCamera.by.by3 = 0;
roDeviceDescriptor.ipCamera.by.by4 = 100;
 
/* Set multicast IP to 239.20.20.1 */
roDeviceDescriptor.ipMulticast.by.by1 = 239;
roDeviceDescriptor.ipMulticast.by.by2 = 20;
roDeviceDescriptor.ipMulticast.by.by3 = 20;
roDeviceDescriptor.ipMulticast.by.by4 = 1;
 
/* Specify the camera ID */
roDeviceDescriptor.u32CameraId = 42;
 
/* Define the error handling */
roDeviceDescriptor.u32ErrorHandlingMode = IS_PMC_ERRORHANDLING_REJECT_IMAGES;
 
/* Enable the multicast mode for the entire system (only once necessary, can be done using IDS Camera Manager */
BOOL enable = TRUE;
int nRet = is_Multicast(0, IS_PMC_CMD_SYSTEM_SET_ENABLE, &enable, sizeof(enable));
 
/* Initialize multicast mode in local API instance. */
nRet = is_Multicast(0, IS_PMC_CMD_INITIALIZE, NULL, 0);
 
/* Create a (virtual) read-only device */
nRet = is_Multicast(0, IS_PMC_CMD_ADDMCDEVICE, &roDeviceDescriptor, sizeof(roDeviceDescriptor));
 
if (nRet == IS_SUCCESS)
{
/* Save all created read-only devices in the system configuration */
nRet = is_Multicast(0, IS_PMC_CMD_STOREDEVICES, NULL, 0);
}
 
/* Alternatively: Remove a device */
/* Set camera IP to 192.168.0.120 */
roDeviceDescriptor.ipCamera.by.by1 = 192;
roDeviceDescriptor.ipCamera.by.by2 = 168;
roDeviceDescriptor.ipCamera.by.by3 = 0;
roDeviceDescriptor.ipCamera.by.by4 = 120;
 
/* Remove a (virtual) read-only device (with IP 192.168.0.120) */
int nRet = is_Multicast(0, IS_PMC_CMD_REMOVEMCDEVICE, &roDeviceDescriptor, sizeof(roDeviceDescriptor));
 
if (nRet == IS_SUCCESS)
{
/* Save all created read-only devices in the system configuration */
nRet = is_Multicast(0, IS_PMC_CMD_STOREDEVICES, NULL, 0);
}

Example 3

/*
* Returns the multicast configuration of a camera.
* This works either in paired state with the device handle or in not paired state with the camera's device ID.
*/
 
/* Not paired: deivce ID of the camera to be configured (from the camera list) */
INT nDeviceId = 1001;
UEYE_ETH_ADDR_IPV4 multicastIp;
 
/* Read multicast IP of the camera 1001 */
int nRet = is_Multicast(nDeviceId | IS_USE_DEVICE_ID, IS_AMC_CMD_GET_MC_IP, &multicastIp,
                      sizeof(multicastIp));
 
unsigned int multicastEnabled;
/* Read status of the multicast mode of camera 1001 */
nRet = is_Multicast(nDeviceId | IS_USE_DEVICE_ID, IS_AMC_CMD_GET_MC_ENABLED, &multicastEnabled,
                  sizeof(multicastEnabled));
 
/* Alternatively in paired state with HIDS camera handle hCam. */
UEYE_ETH_ADDR_IPV4 multicastIp2;
/* Read multicast IP of the opened camera hCam */
nRet = is_Multicast(hCam, IS_AMC_CMD_GET_MC_IP, &multicastIp2, sizeof(multicastIp2));
 
unsigned int multicastEnabled2;
/* Read status of the multicast mode of the opened camera hCam */
nRet = is_Multicast(hCam, IS_AMC_CMD_GET_ENABLED, &multicastEnabled2, sizeof(multicastEnabled2));

Example 4

/* Configuration of the multicast mode of a camera which is not paired */
/* Device ID of the camera to be configured (from the camera list) */
INT nDeviceId = 1001;
UEYE_ETH_ADDR_IPV4 multicastIp;
multicastIp.by.by1 = 239;
multicastIp.by.by2 = 20;
multicastIp.by.by3 = 20;
multicastIp.by.by4 = 1;
 
/* Check if multicast mode is supported by the camera */
IS_U32 nMulticastSupported = 0;
int nRet = is_Multicast(nDeviceId | IS_USE_DEVICE_ID, IS_AMC_CMD_GET_MC_SUPPORTED,
                      &nMulticastSupported, sizeof(nMulticastSupported))
 
bool bMulticastSupportedByDevice = (nMulticastSupported & IS_AMC_SUPPORTED_FLAG_DEVICE);
bool bMulticastSupportedByFirmware = (nMulticastSupported & IS_AMC_SUPPORTED_FLAG_FIRMWARE);
 
if (bMulticastSupportedByDevice && bMulticastSupportedByFirmware)
{
/* Set the multicast IP of camera 1001 to 239.20.20.1 */
nRet = is_Multicast(nDeviceId | IS_USE_DEVICE_ID, IS_AMC_CMD_SET_MC_IP,
                    &multicastIp, sizeof(multicastIp));
unsigned int multicastEnabled = 1;
 
/* Enable the multicast mode of camera 1001 */
nRet = is_Multicast(nDeviceId | IS_USE_DEVICE_ID, IS_AMC_CMD_SET_MC_ENABLED,
                    &multicastEnabled, sizeof(multicastEnabled));
}