UA Part 20: File Transfer - 4.4 Temporary file transfer

This ObjectType defines a type for the representation of temporary file transfers. It is formally defined in Table 13. The Methods GenerateFileForRead or GenerateFileForWrite generate a temporary FileType Object that is not browsable in the AddressSpace and can only be accessed with the NodeId and FileHandle returned by the Methods in the same Session. This Object is used to transfer the temporary file between OPC UA Client and Server.

Table 13 – TemporaryFileTransferType

Attribute	Value
BrowseName	TemporaryFileTransferType
IsAbstract	False
References		NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5
HasProperty		Variable	ClientProcessingTimeout	Duration	PropertyType	Mandatory
HasComponent		Method	GenerateFileForRead	Defined in 4.4.3		Mandatory
HasComponent		Method	GenerateFileForWrite	Defined in 4.4.4		Mandatory
HasComponent		Method	CloseAndCommit	Defined in 4.4.5		Mandatory
HasComponent		Object	<TransferState>		FileTransferStateMachineType	OptionalPlaceholder
Conformance Units
Base Info TemporaryFileTransferType Base

The Property ClientProcessingTimeout defines the maximum time in milliseconds the Server accepts between Method calls necessary to complete a file read transfer or a file write transfer transaction. This includes the Method calls to read or write the file content from the virtual temporary FileType Object. If the Client exceeds the timeout between Method calls, the Server may close the file and cancel the corresponding transfer transaction. Any open temporary transfer file shall be deleted if the Session used to create the file is no longer valid.

The TransferState Objects are used to expose the state of a transfer transaction in the case that the preparation of a file for reading or the processing of the file after writing completes asynchronous after the corresponding Method execution. If the transactions are completed when the Method is returned, the optional TransferState Objects are not available. A Server may allow more than one parallel read transfer. A Server may not allow more than one write transfer or a parallel read and writer transfer.

4.4.2 File transfer sequences

The sequence of Method calls necessary to execute a read file transfer transaction is illustrated in Figure 2.

Figure 2 – Read file transfer example sequence

The read file transfer transaction is started with the Method GenerateFileForRead defined by the TemporaryFileTransferType. After a successful call of this Method, the Client reads the file content by calling the Method Read defined by the FileType until the whole file is transferred from the Server to the Client. The transaction is completed by calling the Method Close defined by the FileType.

The sequence of Method calls necessary to execute a write file transfer transaction is illustrated in Figure 3.

Figure 3 – Write file transfer example sequence

The write file transfer transaction is started with the Method StartWriteTransfer defined by the TemporaryFileTransferType. After a successful call of this Method, the Client writes the file content by calling the Method Write defined by the FileType until the whole file is transferred from the Client to the Server. The transaction is completed by calling the Method CloseAndCommit defined by the TemporaryFileTransferType. If the Client wants to abort the operation it uses the Close Method of the temporary FileType Object.

4.4.3 GenerateFileForRead

GenerateFileForRead is used to start the read file transaction. A successful call of this Method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object.

Signature

GenerateFileForRead(

[in] BaseDataType generateOptions

[out] NodeId fileNodeId

[out] UInt32 fileHandle

[out] NodeId completionStateMachine

);

Argument	Description
generateOptions	The optional parameter can be used to specify server specific file generation options. To allow such options, the Server shall specify a concrete DataType in the Argument Structure for this argument in the instance of the Method. If the DataType is BaseDataType, the Client shall pass Null for this argument. Examples for concrete DataTypes are OptionSetUsed to provide a bit mask for file content selection String Can be used to provide a string filter or a regular expression StructureCan be used to provide a structure with create settings e.g. to create a report EnumerationCan be used to provide a list of options
fileNodeId	NodeId of the temporary file.
fileHandle	The fileHandle of the opened TransferFile. The fileHandle can be used to access the TransferFile Methods Read and Close.
completionStateMachine	If the creation of the file is completed asynchronous, the parameter returns the NodeId of the corresponding FileTransferStateMachineType Object. If the creation of the file is already completed, the parameter is null. If a FileTransferStateMachineType Object NodeId is returned, the Read Method of the file fails until the TransferState changed to ReadTransfer.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_UserAccessDenied	See OPC 10000-4 for a general description.

Table 14 specifies the AddressSpace representation for the GenerateFileForRead Method.

Table 14 – GenerateFileForRead Method AddressSpace definition

Attribute	Value
BrowseName	GenerateFileForRead
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory
Conformance Units
Base Info TemporaryFileTransferType Base

4.4.4 GenerateFileForWrite

GenerateFileForWrite is used to start the write file transaction. A successful call of this Method creates a temporary FileType Object and returns the NodeId of this Object and the file handle to access the Object.

Signature

GenerateFileForWrite(

[in] BaseDataTypegenerateOptions

[out] NodeId fileNodeId

[out] UInt32 fileHandle

);

Argument	Description
generateOptions	The optional parameter can be used to specify server specific file generation options. To allow such options, the Server shall specify a concrete DataType in the Argument Structure for this argument in the instance of the Method. If the DataType is BaseDataType, the Client shall pass Null for this argument. Examples for concrete DataTypes are OptionSetUsed to provide a bit mask for file use selection StructureCan be used to provide a structure with create settings e.g. firmware update settings EnumerationCan be used to provide a list of options like file handling options
fileNodeId	NodeId of the temporary file.
fileHandle	The fileHandle of the opened TransferFile. The fileHandle can be used to access the TransferFile Methods Write and Close.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_UserAccessDenied	See OPC 10000-4 for a general description.

Table 15 specifies the AddressSpace representation for the GenerateFileForWrite Method.

Table 15 – GenerateFileForWrite Method AddressSpace definition

Attribute	Value
BrowseName	GenerateFileForWrite
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory
Conformance Units
Base Info TemporaryFileTransferType Base

4.4.5 CloseAndCommit

CloseAndCommit is used to apply the content of the written file and to delete the temporary file after the completion of the transaction.

Signature

CloseAndCommit(

[in] UInt32 fileHandle

[out] NodeId completionStateMachine

);

Argument	Description
fileHandle	The fileHandle used to write the file.
completionStateMachine	If the processing of the file is completed asynchronous, the parameter returns the NodeId of the corresponding FileTransferStateMachineType Object. If the processing of the file is already completed, the parameter is null. If a FileTransferStateMachineType Object NodeId is returned, the processing is in progress until the TransferState changed to Idle.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_UserAccessDenied	See OPC 10000-4 for a general description.

Table 16 specifies the AddressSpace representation for the CloseAndCommit Method.

Table 16 – CloseAndCommit Method AddressSpace definition

Attribute	Value
BrowseName	CloseAndCommit
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory
Conformance Units
Base Info TemporaryFileTransferType Base

4.4.6 FileTransferStateMachineType

The states of the file transfer state machine are shown in Figure 4.

Figure 4 – File transfer States

The FileTransferStateMachineType and the related type are illustrated in Figure 5.

Figure 5 – FileTransferStateMachineType

This ObjectType defines the StateMachine for asynchronous processing of temporary file transfers. It is formally defined in Table 17. The transitions are formally defined in Table 19.

Table 17 – FileTransferStateMachineType

Attribute	Value
BrowseName	FileTransferStateMachineType
IsAbstract	False
References		NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the FiniteStateMachineType defined in B.4.5.
HasComponent		Object	Idle		InitialStateType
HasComponent		Object	ReadPrepare		StateType
HasComponent		Object	ReadTransfer		StateType
HasComponent		Object	ApplyWrite		StateType
HasComponent		Object	Error		StateType
HasComponent		Object	IdleToReadPrepare		TransitionType
HasComponent		Object	ReadPrepareToReadTransfer		TransitionType
HasComponent		Object	ReadTransferToIdle		TransitionType
HasComponent		Object	IdleToApplyWrite		TransitionType
HasComponent		Object	ApplyWriteToIdle		TransitionType
HasComponent		Object	ReadPrepareToError		TransitionType
HasComponent		Object	ReadTransferToError		TransitionType
HasComponent		Object	ApplyWriteToError		TransitionType
HasComponent		Object	ErrorToIdle		TransitionType
HasComponent		Method	Reset	Defined in 4.4.7		Mandatory
Conformance Units
Base Info TemporaryFileTransferType Base

The component Variables of the FileTransferStateMachineType have additional Attributes defined in Table 18.

Table 18 – FileTransferStateMachineType Attribute values for child Nodes

Source Path

Value Attribute

Idle

StateNumber

ReadPrepare

StateNumber

ReadTransfer

StateNumber

ApplyWrite

StateNumber

Error

StateNumber

IdleToReadPrepare

TransitionNumber

ReadPrepareToReadTransfer

TransitionNumber

ReadTransferToIdle

TransitionNumber

IdleToApplyWrite

TransitionNumber

ApplyWriteToIdle

TransitionNumber

ReadPrepareToError

TransitionNumber

ReadTransferToError

TransitionNumber

ApplyWriteToError

TransitionNumber

ErrorToIdle

TransitionNumber

Table 19 – FileTransferStateMachineType Additional References

SourceBrowsePath	References	IsForward	TargetBrowsePath
IdleToReadPrepare	FromState	True	Idle
	ToState	True	ReadPrepare
	HasEffect	True	TransitionEventType
ReadPrepareToReadTransfer	FromState	True	ReadPrepare
	ToState	True	ReadTransfer
	HasEffect	True	TransitionEventType
ReadTransferToIdle	FromState	True	ReadTransfer
	ToState	True	Idle
	HasEffect	True	TransitionEventType
IdleToApplyWrite	FromState	True	Idle
	ToState	True	ApplyWrite
	HasEffect	True	TransitionEventType
ApplyWriteToIdle	FromState	True	ApplyWrite
	ToState	True	Idle
	HasEffect	True	TransitionEventType
ReadPrepareToError	FromState	True	ReadPrepare
	ToState	True	Error
	HasEffect	True	TransitionEventType
ReadTransferToError	FromState	True	ReadTransfer
	ToState	True	Error
	HasEffect	True	TransitionEventType
ApplyWriteToError	FromState	True	ApplyWrite
	ToState	True	Error
	HasEffect	True	TransitionEventType
ErrorToIdle	FromState	True	Error
	ToState	True	Idle
	HasEffect	True	TransitionEventType

4.4.7 Reset

Reset is used to reset the Error state of a FileTransferStateMachineType Object.

Signature

Reset();

Table 20 specifies the AddressSpace representation for the Reset Method.

Table 20 – Reset Method AddressSpace definition

Attribute	Value
BrowseName	Reset
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
Conformance Units
Base Info TemporaryFileTransferType Base

_____________