This method is used to add a configuration to the configuration management of the vision system. It concerns itself only with the metadata of the configuration, the actual content is transferred by an object of ConfigurationTransferType which is defined in Section 7.4.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

AddConfiguration ([in]ConfigurationIdDataTypeexternalId[out]ConfigurationIdDataTypeinternalId[out]NodeIdconfiguration[out]BooleantransferRequired[out]Int32error);

Table 12 – AddConfiguration Method Arguments

Argument	Description
externalId	Identification of the configuration used by the environment. This argument must not be empty.
internalId	System-wide unique ID for identifying a configuration. This ID is assigned by the vision system.
configuration	If the server chooses to represent the configuration in the Address Space, it shall return the NodeId of the newly created entry in the Configurations variable here. If the server uses only method-based configuration management, this shall be a null NodeId as defined in OPC 10000-3.
transferRequired	In this argument, the server returns whether the vision system assumes that a transfer of the file content of the configuration is required. Note that this is only a hint for the client. If the server returns TRUE, the client will have to assume that the vision system needs the configuration content and shall transfer it. If the server returns FALSE, the client may transfer the configuration content anyway.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 13 – AddConfiguration Method AddressSpace Definition

Attribute	Value
BrowseName	AddConfiguration
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If AddConfiguration is called with an ExternalId not yet existing in the configuration management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is unique on the system. The server then returns this InternalId.

If the server chooses to represent all or selected configurations in the Address Space and if the new configuration matches the current selection criteria, the server shall create a new entry in the Configurations folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the configuration management of the vision system, it is expected the configuration does not yet exist either in the local configuration storage of the vision system, and therefore needs to be transferred.

If AddConfiguration is called with an ExternalId already existing in the configuration management of the vision system, it is expected that the vision system checks whether an identical version of the configuration already exists, provided that the content of the ExternalId allows for such a check. (A way to perform this comparison without having to download the binary content first is offered by the optional hash value in the ExternalId. The idea is that the client computes a hash for the contents of the recipe and passes that hash in the ExternalId. The server can then check this hash against a hash transmitted earlier, or it can compute a hash by itself over the contents of the recipe currently stored on the vision system side. For this procedure, the server needs to know the hash algorithm used by the client which can be transmitted in the hashAlgorithm member of the ExternalId).

Note that the method has no way of checking this with the actual configuration content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the method comes to the conclusion that the configuration already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the configuration content anyway.

If the server represents configurations in the Address Space, no new entry shall be created in the configurations folder.

If AddConfiguration comes to the conclusion that the content of the configuration to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the configuration metadata and configuration content is entirely application-defined. The vision system may decide to create a new management structure and add the configuration content to the local configuration store, or it may decide to re-use the existing ExternalId and overwrite the configuration content. In any case, the vision system shall create a new, system-wide unique InternalId for this configuration.

If the server chooses to represent configurations in the Address Space, the behavior with respect to these objects should mirror the behavior of the vision system in its internal configuration management.

This is not, strictly speaking, a use case of the method AddConfiguration, but results are comparable, and therefore the use case is described here.

If a configuration is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the configuration is added without using method AddConfiguration, then this configuration shall have a system-wide unique InternalId, just like a configuration added through the method.

If an existing configuration which was uploaded to the vision system through the method AddConfiguration, is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two configurations cannot be confused. The vision system may record the history from which configuration it was derived.

If the server exposes configurations in the Address Space and if the locally created or edited configurations match the current filter criteria, then they shall be represented as nodes in the Configurations folder, with their system-wide unique InternalIds, but without ExternalIds.

This method is used to get the metadata for one configuration from a number of configurations.

Signature

GetConfigurationById ([in]ConfigurationIdDataTypeinternalId[in]Int32timeout[out]HandleconfigurationHandle[out]ConfigurationDataTypeconfiguration[out]Int32error);

Table 14 – GetConfigurationById Method Arguments

Argument	Description
internalId	Identification of the configuration used by the vision system. This argument must not be empty.
Timeout	With this argument the client can give a hint to the server how long it will need access to the configuration data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the client will not need anything besides the data returned by the method call. A value < 0 indicates that the client cannot give an estimate. The client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the server to optimize its resource management.
configurationHandle	The client can use the handle returned by the server to call the ReleaseConfigurationHandle method to indicate to the server that it has finished processing the configuration data, allowing the server to optimize its resource management. If the server does not support the ReleaseConfigurationHandle method, this value shall be 0. The client cannot rely on the data being available until ReleaseConfigurationHandle is called.
configuration	Requested configuration.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 15 – GetConfigurationById Method AddressSpace Definition

Attribute	Value
BrowseName	GetConfigurationById
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

This method is used to get a list of all configurations. It concerns itself only with the metadata of the configuration, the actual content is transferred by a ConfigurationTransferType object.

Signature

GetConfigurationList ([in]UInt32maxResults[in]UInt32startIndex[in]Int32timeout[out]BooleanisComplete[out]UInt32resultCount[out]HandleconfigurationHandle[out]ConfigurationDataType[]configurationList[out]Int32error);

Table 16 – GetConfigurationList Method Arguments

Argument	Description
maxResults	Maximum number of configurations to return in one call; by passing 0, the client indicates that it does not put a limit on the number of configurations.
startIndex	Shall be 0 on the first call, multiples of maxResults on subsequent calls to retrieve portions of the entire list, if necessary.
timeout	With this argument the client can give a hint to the server how long it will need access to the configuration data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the client will not need anything besides the data returned by the method call. A value < 0 indicates that the client cannot give an estimate. The client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the server to optimize its resource management.
isComplete	Indicates whether there are more configurations in the entire list than retrieved according to startIndex and resultCount.
resultCount	Gives the number of valid results in configurationList.
configurationHandle	The server shall return to each client requesting configuration data a system-wide unique handle identifying the configuration set / client combination. The handle spans continuation calls, so on every call by the same client where startIndex is not 0, the same handle shall be returned. This handle canbe used by the client in a call to the ReleaseConfigurationHandle method, thereby indicating to the server that it has finished processing the configuration set, allowing the server to optimize its resource management. The client cannot rely on the data being available until the ReleaseConfigurationHandle method is called. If the server does no support ReleaseConfigurationHandle, this value shall be 0.
configurationList	List of configurations.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 17 – GetConfigurationList Method AddressSpace Definition

Attribute	Value
BrowseName	GetConfigurationList
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

The following cases must be considered with the respect to the number of available configurations:

• The number of configurations to be returned is less or equal to maxResults; the first call, with startIndex =0, returns isComplete =TRUE, so the client knows that no further calls are necessary. resultCount gives the number of valid elements in the configurationList array.
• The number of configurations to be returned is larger than maxResults; the first N calls (N > 0 with N ≤ (number of configurations) divisor MaxResults), with startIndex =(N-1)*maxResults, return isComplete =FALSE, so the client knows that further calls are necessary. The following call returns isComplete =TRUE, so the client knows, no further calls are necessary. resultCount gives the number of valid elements in the configurationList array (on each call, so on the first N calls, this should be maxResults).

This method is used to inform the server that the client has finished processing a given configuration set allowing the server to free resources managing this configuration set.

The server should keep the data of the configuration set available for the client until the ReleaseConfigurationHandle method is called or until a timeout given by the client has expired. However, the server is free to release the data at any time, depending on its internal resource management, so the client cannot rely on the data being available. ReleaseConfigurationHandle is merely a hint allowing the server to optimize its internal resource management. For timeout usage, see the description in Section 7.2.2.2.

Signature

ReleaseConfigurationHandle ([in]HandleconfigurationHandle[out]Int32 error);

Table 18 – ReleaseConfigurationHandle Method Arguments

Argument	Description
configurationHandle	Handle returned by GetConfigurationById or GetConfigurationList, identifying the configuration set/client combination.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 19 – ReleaseConfigurationHandle Method AddressSpace Definition

Attribute	Value
BrowseName	ReleaseConfigurationHandle
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

This method is used to remove a configuration from the configuration management of the vision system.

Application Note:

It may be required from a vision system – e.g. in pharmaceutical or other safety-critical applications – to keep a record of the prior existence of a removed configuration. This may be important in such systems for the meta information of results that were generated while the removed configuration was active. It serves to keep it comprehensible which configurations were available on the vision system

Signature

RemoveConfiguration ([in]ConfigurationIdDataTypeinternalId[out]Int32error);

Table 20 – RemoveConfiguration Method Arguments

Argument	Description
internalId	Identification of the configuration used by the vision system. This argument must not be empty.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 21 – RemoveConfiguration Method AddressSpace Definition

Attribute	Value
BrowseName	RemoveConfiguration
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

This method is used to activate a configuration from the configuration management of the vision system.

Since only a single configuration can be active at any time, this method shall deactivate any other configuration which may currently be active. From that point on until the next call to this method the vision system will conduct its operation according to the settings of the activated configuration.

Note that there is no way to deactivate a configuration except by activating another one to avoid having no active configuration on the system.

Signature

ActivateConfiguration ([in]ConfigurationIdDataTypeinternalId[out]Int32error);

Table 22 – ActivateConfiguration Method Arguments

Argument	Description
internalId	Identification of the configuration used by the vision system. This argument must not be empty.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 23 – ActivateConfiguration Method AddressSpace Definition

Attribute	Value
BrowseName	ActivateConfiguration
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory