OPC UA Specification
OPC 10000-20
OPC Unified Architecture Part 20: File Transfer     Release 1.05.03 2023-12-31

 

 

 

 

 

 

CONTENTS

FIGURES. ii

TABLES. iii

1       Scope. 1

2       Normative references 1

3       Terms, definitions, abbreviated terms and conventions 1

3.1         Terms and definitions. 1

4       File Transfer Model 1

4.1         Overview. 1

4.2         FileType. 2

4.2.1           General 2

4.2.2           Open. 3

4.2.3           Close. 4

4.2.4           Read. 4

4.2.5           Write. 5

4.2.6           GetPosition. 6

4.2.7           SetPosition. 6

4.3         File System. 7

4.3.1           FileDirectoryType. 7

4.3.2           FileSystem Object 7

4.3.3           CreateDirectory 8

4.3.4           CreateFile. 9

4.3.5           Delete. 9

4.3.6           MoveOrCopy 10

4.4         Temporary file transfer 11

4.4.1           TemporaryFileTransferType 11

4.4.2           File transfer sequences 12

4.4.3           GenerateFileForRead. 13

4.4.4           GenerateFileForWrite. 14

4.4.5           CloseAndCommit 14

4.4.6           FileTransferStateMachineType. 15

4.4.7           Reset 18

 

FIGURES

 

Figure 1 – FileSystem example............................................................................... 8

Figure 2 – Read file transfer example sequence........................................................ 12

Figure 3 – Write file transfer example sequence........................................................ 12

Figure 4 – File transfer States.............................................................................. 15

Figure 5 – FileTransferStateMachineType............................................................... 16

 

 

TABLES

 

Table 1 – FileType.............................................................................................. 2

Table 2 – Open Method AddressSpace definition........................................................ 4

Table 3 – Close Method AddressSpace definition........................................................ 4

Table 4 – Read Method AddressSpace definition........................................................ 5

Table 5 – Write Method AddressSpace definition........................................................ 6

Table 6 – GetPosition Method AddressSpace definition................................................ 6

Table 7 – SetPosition Method AddressSpace definition................................................ 7

Table 8 – FileDirectoryType................................................................................... 7

Table 9 – CreateDirectory Method AddressSpace definition........................................... 9

Table 10 – CreateFile Method AddressSpace definition................................................ 9

Table 11 – Delete Method AddressSpace definition.................................................... 10

Table 12 – MoveOrCopy Method AddressSpace definition........................................... 11

Table 13 – TemporaryFileTransferType................................................................... 11

Table 14 – GenerateFileForRead Method AddressSpace definition................................ 13

Table 15 – GenerateFileForWrite Method AddressSpace definition................................ 14

Table 16 – CloseAndCommit Method AddressSpace definition...................................... 15

Table 17 – FileTransferStateMachineType............................................................... 16

Table 18 – FileTransferStateMachineType Attribute values for child Nodes...................... 17

Table 19 – FileTransferStateMachineType Additional References.................................. 18

Table 20 – Reset Method AddressSpace definition.................................................... 18

 

OPC Foundation

____________

 

UNIFIED ARCHITECTURE –

FOREWORD

This specification is the specification for developers of OPC UA applications. The specification is a result of an analysis and design process to develop a standard interface to facilitate the development of applications by multiple vendors that shall inter-operate seamlessly together.

Copyright © 2006-2023, OPC Foundation, Inc.

AGREEMENT OF USE

COPYRIGHT RESTRICTIONS

Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.

OPC Foundation members and non-members are prohibited from copying and redistributing this specification. All copies must be obtained on an individual basis, directly from the OPC Foundation Web site http://www.opcfoundation.org.

PATENTS

The attention of adopters is directed to the possibility that compliance with or adoption of OPC specifications may require use of an invention covered by patent rights. OPC shall not be responsible for identifying patents for which a license may be required by any OPC specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.

WARRANTY AND LIABILITY DISCLAIMERS

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you.

RESTRICTED RIGHTS LEGEND

This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation, 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830.

COMPLIANCE

The OPC Foundation shall at all times be the sole entity that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.

Trademarks

Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.

GENERAL PROVISIONS

Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.

This Agreement shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.

This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.

ISSUE REPORTING

The OPC Foundation strives to maintain the highest quality standards for its published specifications, hence they undergo constant review and refinement. Readers are encouraged to report any issues and view any existing errata here: http://www.opcfoundation.org/errata.

Revision 1.05.03 Highlights

The following table includes the Mantis issues resolved with this revision.

 

Mantis ID	Scope	Summary	Resolution
	Clarification	IEC Requested changes	Fixes applied

OPC Unified Architecture Specification

 

Part 20: File Transfer

 

 

 

1     Scope

This part of the OPC Unified Architecture defines an Information Model. The Information Model describes the basic infrastructure to model file transfers.

2     Normative references

The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC Unified Architecture - Part 1: Concepts

http://www.opcfoundation.org/UA/Part1/

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

http://www.opcfoundation.org/UA/Part3/

OPC 10000-4, OPC Unified Architecture - Part 4: Services

http://www.opcfoundation.org/UA/Part4/

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

http://www.opcfoundation.org/UA/Part5/

3     Terms, definitions, abbreviated terms and conventions

3.1       Terms and definitions

For the purposes of this document, the terms and definitions given in OPC 10000-1, OPC 10000-3 and OPC 10000-5 apply.

4     File Transfer Model

4.1       Overview

This document describes an information model for file transfer. Files could be modelled in OPC UA as simple Variables using ByteStrings. However, the overall message size in OPC UA is limited due to resources and security issues (denial of service attacks). Only accessing parts of the array can lead to concurrency issues if one client is reading the array while others are manipulating it. Therefore, the ObjectType FileType is defined representing a file with Methods to access the file. The life-cycle of a file stored on a hard disk and an instance of the FileType representing the file in an OPC UA AddressSpace can be independent.

In addition to representing individual files this document also defines a way to represent a whole file system or a part of a file system. This can be done using the FileDirectoryType in combination with the FileType. The FileDirectoryType provides Methods to create, delete, and move files and directories. The root of a file system or part of a file system is represented by an instance of the FileDirectoryType with the BrowseName FileSystem. All directories below the root directory are represented by instances of the FileDirectoryType or a subtype. All files below the root directory are represented by instances of the FileType or a subtype.

In different situations like transfer of configuration files or firmware update, the files are temporary, and an additional handshake is necessary to create the file for reading or to apply the file after writing it to the server. This use case is covered by the TemporaryFileTransferType defined in this document.

4.2       FileType

4.2.1        General

This ObjectType defines a type for files. It is formally defined in Table 1.

Table 1 – FileType

 

Size defines the size of the file in Bytes. When a file is opened for write, the size might not be accurate. If the Server can not accurately determine the size of the file, the Size Property shall be returned to a Client with a StatusCode of Bad_NotSupported.

Writable indicates whether the file is writable. It does not take any user access rights into account, i.e., although the file is writable this may be restricted to a certain user / user group. The Property does not consider whether the file is currently opened for writing by another client and thus currently locked and not writable by others.

UserWritable indicates whether the file is writable taking user access rights into account. The Property does not consider whether the file is currently opened for writing by another client and thus currently locked and not writable by others.

OpenCount indicates the number of currently valid file handles on the file.

The optional Property MimeType contains the media type of the file based on RFC 2046.

Note that all Methods on a file require a fileHandle, which is returned in the Open Method.

The optional MaxByteStringLength Property indicates the maximum number of bytes of the read and write buffers. If this Property is not present then the maximum size is defined by the MaxByteStringLength Property of the ServerCapabilitiesType defined in OPC 10000-5.

The optional LastModifiedTime Property indicates the time the file was last modified. The Property shall be updated whenever the Server detects that the file has changed.

4.2.2       Open

Open is used to open a file represented by an Object of FileType. When a client opens a file it gets a file handle that is valid while the session is open. Clients shall use the Close Method to release the handle when they do not need access to the file anymore. Clients can open the same file several times for read. A request to open for writing shall return Bad_NotWritable when the file is already opened. A request to open for reading shall return Bad_NotReadable when the file is already opened for writing.

Signature

Open(

    [in] Byte mode

    [out] UInt32 fileHandle

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 2 specifies the AddressSpace representation for the Open Method.

Table 2 – Open Method AddressSpace definition

 

4.2.3        Close

Close is used to close a file represented by a FileType. When a client closes a file, the handle becomes invalid.

Signature

Close(

    [in] UInt32 fileHandle

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 3 specifies the AddressSpace representation for the Close Method.

Table 3 – Close Method AddressSpace definition

 

4.2.4        Read

Read is used to read a part of the file starting from the current file position. The file position is advanced by the number of bytes read.

Signature

Read(

    [in] UInt32 fileHandle

    [in] Int32 length

    [out] ByteString data

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 4 specifies the AddressSpace representation for the Read Method.

Table 4 – Read Method AddressSpace definition

 

4.2.5        Write

Write is used to write a part of the file starting from the current file position. The file position is advanced by the number of bytes written.

Signature

Write(

    [in] UInt32 fileHandle

    [in] ByteString data

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 5 specifies the AddressSpace representation for the Write Method.

Table 5 – Write Method AddressSpace definition

 

4.2.6        GetPosition

GetPosition is used to provide the current position of the file handle.

Signature

GetPosition(

    [in] UInt32 fileHandle

    [out] UInt64 position

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 6 specifies the AddressSpace representation for the GetPosition Method.

Table 6 – GetPosition Method AddressSpace definition

 

4.2.7        SetPosition

SetPosition is used to set the current position of the file handle.

Signature

SetPosition(

    [in] UInt32 fileHandle

    [in] UInt64 position

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 7 specifies the AddressSpace representation for the SetPosition Method.

Table 7 – SetPosition Method AddressSpace definition

 

4.3       File System

4.3.1        FileDirectoryType

This ObjectType defines a type for the representation of file directories. It is formally defined in Table 8.

It is expected that OPC UA Servers will create vendor-specific subtypes of the FileDirectoryType with additional functionalities like Methods for creating symbolic links or setting access permissions. OPC UA Clients providing specialized file transfer user interfaces should be prepared to expose such additional Methods to the user.

Table 8 – FileDirectoryType

 

Instances of the ObjectType contain a list of FileDirectoryType Objects representing the subdirectories of the file directory represented by the instance of this ObjectType.

Instances of the ObjectType contain a list of FileType Objects representing the files in the file directory represented by the instance of this ObjectType.

4.3.2        FileSystem Object

The support of file directory structures is declared by aggregating an instance of the FileDirectoryType with the BrowseName FileSystem as illustrated in Figure 1.

Figure 1 – FileSystem example

The Object representing the root of a file directory structure shall have the BrowseName FileSystem. An OPC UA Server may have different FileSystem Objects in the AddressSpace. HasComponent is used to reference a FileSystem from aggregating Objects like the Objects Folder or the Object representing a device.

4.3.3        CreateDirectory

CreateDirectory is used to create a new FileDirectoryType Object organized by this Object.

Signature

CreateDirectory(

    [in] String     directoryName

    [out] NodeId    directoryNodeId

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 9 specifies the AddressSpace representation for the CreateDirectory Method.

Table 9 – CreateDirectory Method AddressSpace definition

 

4.3.4        CreateFile

CreateFile is used to create a new FileType Object organized by this Object. The created file can be written using the Write Method of the FileType.

Signature

CreateFile(

    [in] String     fileName

    [in] Boolean    requestFileOpen

    [out] NodeId    fileNodeId

    [out] UInt32    fileHandle

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 10 specifies the AddressSpace representation for the CreateFile Method.

Table 10 – CreateFile Method AddressSpace definition

 

4.3.5        Delete

Delete is used to delete a file or directory organized by this Object.

Signature

Delete(

    [in] NodeId objectToDelete

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 11 specifies the AddressSpace representation for the Delete Method.

Table 11 – Delete Method AddressSpace definition

 

4.3.6        MoveOrCopy

MoveOrCopy is used to move or copy a file or directory organized by this Object to another directory or to rename a file or directory.

Signature

MoveOrCopy(

    [in] NodeId     objectToMoveOrCopy

    [in] NodeId     targetDirectory

    [in] Boolean    createCopy

    [in] String     newName

    [out] NodeId    newNodeId

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 12 specifies the AddressSpace representation for the MoveOrCopy Method.

Table 12 – MoveOrCopy Method AddressSpace definition

 

4.4       Temporary file transfer

4.4.1        TemporaryFileTransferType

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

 

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

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 14 specifies the AddressSpace representation for the GenerateFileForRead Method.

Table 14 – GenerateFileForRead Method AddressSpace definition

 

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] BaseDataType    generateOptions

    [out] NodeId         fileNodeId

    [out] UInt32         fileHandle

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 15 specifies the AddressSpace representation for the GenerateFileForWrite Method.

Table 15 – GenerateFileForWrite Method AddressSpace definition

 

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

   );

 

 

Method Result Codes (defined in Call Service)

 

Table 16 specifies the AddressSpace representation for the CloseAndCommit Method.

Table 16 – CloseAndCommit Method AddressSpace definition

 

 

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

 

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

Table 18 – FileTransferStateMachineType Attribute values for child Nodes

 

Table 19 – FileTransferStateMachineType Additional References

 

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

 

_____________