The specialized EasyUAFileTransferClient object allows you to make OPC UA file transfer operations easily, without having to deal with details of the corresponding OPC UA service or method calls. You do not have study the OPC UA specifications and write low-level code to make each method call; all this knowledge is already encapsulated in the specialized client object for you. For example, you can directly call methods such as OpenFile or ReadFile, without having to know the method Ids and how to put together the array of method arguments and dissect the result.
This article describes API levels 2 and 2+ for OPC UA File Transfer (the EasyUAFileTransferClient Class together with the extension methods defined in the IEasyUAFileTransferExtension Class). For an overview of API levels, see OPC UA File Transfer.
The features discussed here, or some of them, may not be available in all editions of the product. Check the
OPC Data Client Product Editions page for differences between the editions. The trial license has all features enabled (and is limited in period for which it provides valid data), but licenses for specific commercial editions may have functionality limitations.
This functionality is not available under (or the text does not apply to) COM development platform.
Operations overview
Methods (the basic set, i.e. API level 2, IEasyUAFileTransferClient Interface) are available to:
- Obtain information about specific files
- Create, open and close files
- Read data from and write data to files
- Get and set position in the file
- Delete files
- Create and delete directories
- Move or copy files and directories
- List contents of directories
- Finding files, directories, and finding a parent directory
- Finding a file system on a specified OPC UA object
- Determining whether the specified node represents a file or directory
Extensions methods (i.e. API level 2+, in IEasyUAFileTransferExtension Class) are used to expose more overloads (different structure of arguments) to the above methods, and to provide more complex functionality. Also, the extension methods provide distinction between files and directories where the OPC UA File Transfer does not: For example, if you specifically want to move a file, you need to be sure that you do not move a directory that happens to have the same name. The "raw" OPC UA File Transfer do not make this distinction. Other extension methods are available to:
- Find a directory given the named path, or create all directories on the path
- Find a root directory
- Find a (reverse) path to the root directory
You may want to look at OPC UA File Transfers internals in order to understand a bit of what is happening "under the hood".
Error model
The error model of OPC UA File Transfer Client object is as described in Error Model in imperative programming. In short, leaving aside usage errors (incorrect arguments or invalid operations, which can be prevented and do not appear in correctly written code), most methods throw only UAException. Methods that return OperationResult (or an array of them) do not indicate errors by throwing exceptions at all, but instead, you can inspect the Exception Property after the method has returned.
File handles
An OPC UA file handle encapsulates an access request to the OPC UA file. It is represented by the UAFileHandle Class, and returned by some of the methods, such as CreateFile Method or OpenFile Method. The handle is then subsequently used in methods like ReadFile or WriteFile. When you are finished with accessing the OPC UA file, your code should call the CloseFile Method with the handle, and also dispose of the OPC file handle object using its IDisposable.Dispose Method (this can be achieved in C# or VB.NET by the means of the "using" statement).
Dealing with OPC UA file handles is somewhat cumbersome, and you may want to consider using OPC UA File Streams for accessing the file data instead.
Reading and writing file data
In order to read from and/or write to a file:
- Open or create the file and obtain the file handle: The OpenFile Method, CreateFile Method, their extension methods with a different structure of arguments, or the CreateAndOpenFile Method or CreateOrOpenFile Method extension methods.
- If needed, use the file position to navigate inside the file: The GetFilePosition Method, the SetFilePosition Method.
- Perform the actual reads and writes: ReadFile Method, WriteFile Method.
- When finished, close the file handle and dispose of the file handle object: CloseFile Method, IDisposable.Dispose Method.
Note that when using methods from API level 2 and 2+, OPC Data Client automatically provides read/write chunking, but no file data buffering (see OPC UA File Transfer internals for more information). Use OPC UA File Streams if file data buffering is needed.
Reading
The example below shows how to read different sections from an OPC UA file, using the file transfer client.
.NET
Python
If you want to read the whole contents of a file at once, you can use extension methods described in OPC UA File Streams.
Writing
The example below shows how to write data into a section of an OPC UA file, using the file transfer client.
.NET
Python
If you want to write the whole contents of a file at once, you can use extension methods described in OPC UA File Streams.
Creating, deleting, copying and moving files and directories
You will find following (and more) functionality in this group of methods:
- Create a directory: The CreateDirectory Method.
- Delete files and/or directories: The general Delete Method, and the more specific or qualified extension methods: DeleteDirectory Method, DeleteDirectoryIfExists Method, DeleteFile Method, DeleteFileIfExists Method, DeleteIfExists Method.
- Copy or move files and/or directories: The MoveOrCopy Method, and the more specific extension methods: Copy Method, CopyFile Method, Move Method, MoveDirectory Method, MoveFile Method, MoveOrCopy Method, MoveOrCopyDirectory Method, MoveOrCopyFile Method.
- Rename files and/or directories: The Rename Method (extension).
- Find a directory if it exists; create the directory (also optionally together with the directories on the path), if not found: FindOrCreateDirectory Method, FindOrCreateDirectory Method (extension).
The FindXXXX methods (except for FindOrCreateXXXX methods) return a null reference when the specified object does not exist. The GetXXXX methods return an error (throw an exception) if the specified object does not exist.
The example below shows how to create and delete OPC UA directories, using the file transfer client.
.NET
Python
The example below shows how to copy an OPC UA file, using the file transfer client.
.NET
Python
Navigation among files and directories
This group of methods provides following functionality:
- Find or get files and directories by name: The FindFile Method and the FindDirectory Method, and their extension methods with a different structure of arguments, or more functionality: FindFileOrDirectory Method, GetDirectory Method, GetFile Method, GetFileOrDirectory Method.
- Find or get an aggregated file system: The FindFileSystem Method, and its extension method(s) with a different structure of arguments, and the GetFileSystem Method (extension).
- Test whether an OPC UA object aggregates a file system: The HasFileSystem Method (extension).
- Find or get parent directory: The FindParentDirectory Method, the GetParentDirectory Method (extension).
- Test whether a file or directory has a parent directory: The HasParentDirectory Method (extension).
- Find or get the root directory: The FindRootDirectory Method (extension), the GetRootDirectory Method (extension).
- Find the root directory and the path from the root to the given object: The FindRootAndPath Method (extension).
- Test whether a given node is a directory, or a file: The IsDirectory Method, the IsFile Method, the IsFileOrDirectory Method (extension).
- Test whether a given node is a root directory: The IsRootDirectory Method (extension).
Getting information about files and directories
This group of methods provides following (and more) operations:
- Get properties (metadata) of a file or multiple files: the GetMultipleFileProperties Method and its extension method(s) with a different structure of arguments, the GetFileProperties Method (extension).
- Get name of a file or directory (or multiple files or directories), given its node (their nodes): The GetMultipleNames Method, and the related extensions - the GetDirectoryName Method, the GetFileName Method, the GetName Method.
- Obtain names of files or directories under the specified parent directory: The ListFileNames Method, the ListDirectoryNames Method, their extension methods with a different structure of arguments, and the ListFileAndDirectoryNames Method (extension).
- Browse for file and/or directory names together with their node descriptors: The BrowseDirectories Method, the BrowseFiles Method (extension).
- Browse a tree of objects (files, directories) available in the directory: The BrowseTree Method (extension).
The example below shows how to get OPC UA file properties (such as its size or writable status), using the file transfer client.
.NET
Python
The example below shows how to browse for OPC UA files, using the file transfer client.
.NET
Python
See Also
Examples - Client OPC UA File Transfer
Knowledge Base
