7.8.5.2 CloseAndUpdate
The CloseAndUpdate Method closes the ConfigurationFile and applies the changes to the configuration. It can only be called if the ConfigurationFile was opened for writing. If the Close Method is called any cached data is discarded and the configuration is not changed.
The Client may partially update the configuration by specifying one or more targets. Each target refers to a component of the configuration that will be inserted, updated or deleted. The Server shall attempt to apply all changes. If any errors occur then all changes are rolled back.
Updating the configuration will often require the endpoints to be closed and all active Sessions be interrupted. When the new configuration is applied it is possible that a configuration error made the Server unreachable. The RestartDelayTime argument is used to delay the restart process to give the Client a chance to receive results from the CloseAndUpdate call. The RevertAfterTime argument is used to automatically restore the previous configuration if the Client is not able to reconnect and call the ConfirmUpdate Method.
If auditing is supported, the Server shall generate the ConfigurationUpdatedAuditEventType (see 7.8.5.8) when the configuration is updated. This may occur before CloseAndUpdate completes or when the update is scheduled to occur based on the RestartDelayTime.
Signature
CloseAndUpdate(
[in] 0:UInt32 FileHandle
[in] 0:VersionTime VersionToUpdate
[in] 0:ConfigurationUpdateTargetType[] Targets
[in] 0:Duration RevertAfterTime
[in] 0:Duration RestartDelayTime
[out] 0:StatusCode[] UpdateResults
[out] 0:VersionTime NewVersion
[out] 0:Guid UpdateId
);| Argument | Description |
| FileHandle | The handle of the previously opened file. |
| VersionToUpdate | Specifies the version of the configuration that the Client believes it is updating. If the CurrentVersion is not the same a Bad_InvalidState error is returned. |
| Targets | The list of targets to update. There must be at least one target. Contents of the file which are not referenced by a target are ignored. |
| RevertAfterTime | How long the Server should wait before reverting the configuration changes if ConfirmUpdate is not called after CloseAndUpdate returns a response. The RevertAfterTime countdown starts after the RestartDelayTime time elapses. After getting a response, the Client must wait at least RestartDelayTime before attempting to reconnect but no longer than RestartDelayTime + RevertAfterTime. |
| RestartDelayTime | How long the Server should wait before applying the configuration changes if applying the configuration changes will interrupt active Sessions. Clients set this value based on how long it takes for them to receive the response to the Method. |
| UpdateResults | The result for each target update operation. The length and order of the array shall match the targets array. If any element is not Good then then no changes are applied and the Method return code is Uncertain. |
| NewVersion | The new ConfigurationVersion. If it is NULL, then no changes were applied. |
| UpdateId | An id to passed into ConfirmUpdate to tell the Server that the update was successful. If this value is a NULL Guid then ConfirmUpdate does not need to be called. |
Method Result Codes (defined in Call Service)
| Result Code | Description |
| Uncertain | Errors occurred processing individual targets. |
| Bad_UserAccessDenied | The current user does not have the rights required. |
| Bad_InvalidState | The VersionToUpdate does not match the CurrentVersion. |
| Bad_ChangesPending | Changes are queued on another Session (see 7.10.9) |
| Bad_SecurityModeInsufficient | The SecureChannel is not authenticated. |
Operation Result Codes (Returned in UpdateResults)
| Result Code | Description |
| Bad_NoEntryExists | An existing record was not found. |
| Bad_EntryExists | Another record with the same name was found. |
| Good_EntryInserted | A new record was created successfully, |
| Good_EntryReplaced | An existing record was updated successfully, |
| Bad_NoDeleteRights | A record exists but it cannot be deleted. |
| Bad_NotSupported | A field in the record cannot be changed to the value specified. |
| Bad_InvalidArgument | The target definition is not valid. |
| Bad_ResourceUnavailable | The maximum number of supported elements would be exceeded. |
| Bad_InvalidState | The current state of the record does not allow the operation. For example, a CertificateGroup has Certificates assigned. |
Table 29 specifies the AddressSpace representation for the CloseAndUpdate Method.
| Attribute | Value | ||||
| BrowseName | 0:CloseAndUpdate | ||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | Mandatory |