File service related functions, data types, and definitions

Typedefs
typedef struct sFileDirectoryEntry *	FileDirectoryEntry
typedef bool(*	IedConnection_FileDirectoryEntryHandler) (uint32_t invokeId, void *parameter, IedClientError err, char *filename, uint32_t size, uint64_t lastModfified, bool moreFollows)
	Callback handler for the get file directory service. More...
typedef bool(*	IedClientGetFileHandler) (void *parameter, uint8_t *buffer, uint32_t bytesRead)
	user provided handler to receive the data of the GetFile request More...
typedef bool(*	IedConnection_GetFileAsyncHandler) (uint32_t invokeId, void *parameter, IedClientError err, uint32_t originalInvokeId, uint8_t *buffer, uint32_t bytesRead, bool moreFollows)
	User provided handler to receive the data of the asynchronous GetFile request. More...

Functions
LIB61850_API FileDirectoryEntry	FileDirectoryEntry_create (const char *fileName, uint32_t fileSize, uint64_t lastModified)
LIB61850_API void	FileDirectoryEntry_destroy (FileDirectoryEntry self)
	Destroy a FileDirectoryEntry object (free all resources) More...
LIB61850_API const char *	FileDirectoryEntry_getFileName (FileDirectoryEntry self)
	Get the name of the file. More...
LIB61850_API uint32_t	FileDirectoryEntry_getFileSize (FileDirectoryEntry self)
	Get the file size in bytes. More...
LIB61850_API uint64_t	FileDirectoryEntry_getLastModified (FileDirectoryEntry self)
	Get the timestamp of last modification of the file. More...
LIB61850_API LinkedList	IedConnection_getFileDirectory (IedConnection self, IedClientError *error, const char *directoryName)
	returns the directory entries of the specified file directory. More...
LIB61850_API LinkedList	IedConnection_getFileDirectoryEx (IedConnection self, IedClientError *error, const char *directoryName, const char *continueAfter, bool *moreFollows)
	returns the directory entries of the specified file directory returned by a single file directory request. More...
LIB61850_API uint32_t	IedConnection_getFileDirectoryAsyncEx (IedConnection self, IedClientError *error, const char *directoryName, const char *continueAfter, IedConnection_FileDirectoryEntryHandler handler, void *parameter)
	Get file directory (single request) - asynchronous version. More...
LIB61850_API uint32_t	IedConnection_getFile (IedConnection self, IedClientError *error, const char *fileName, IedClientGetFileHandler handler, void *handlerParameter)
	Implementation of the GetFile ACSI service. More...
LIB61850_API uint32_t	IedConnection_getFileAsync (IedConnection self, IedClientError *error, const char *fileName, IedConnection_GetFileAsyncHandler handler, void *parameter)
	Implementation of the GetFile ACSI service - asynchronous version. More...
LIB61850_API void	IedConnection_setFilestoreBasepath (IedConnection, const char *basepath)
	Set the virtual filestore basepath for the setFile service. More...
LIB61850_API void	IedConnection_setFile (IedConnection self, IedClientError *error, const char *sourceFilename, const char *destinationFilename)
	Implementation of the SetFile ACSI service. More...
LIB61850_API uint32_t	IedConnection_setFileAsync (IedConnection self, IedClientError *error, const char *sourceFilename, const char *destinationFilename, IedConnection_GenericServiceHandler handler, void *parameter)
	Implementation of the SetFile ACSI service - asynchronous version. More...
LIB61850_API void	IedConnection_deleteFile (IedConnection self, IedClientError *error, const char *fileName)
	Implementation of the DeleteFile ACSI service. More...
LIB61850_API uint32_t	IedConnection_deleteFileAsync (IedConnection self, IedClientError *error, const char *fileName, IedConnection_GenericServiceHandler handler, void *parameter)
	Implementation of the DeleteFile ACSI service - asynchronous version. More...

Detailed Description

Typedef Documentation

FileDirectoryEntry

typedef struct sFileDirectoryEntry* FileDirectoryEntry

IedClientGetFileHandler

typedef bool(* IedClientGetFileHandler) (void *parameter, uint8_t *buffer, uint32_t bytesRead)

user provided handler to receive the data of the GetFile request

This handler will be invoked whenever the clients receives a data block from the server. The API user has to copy the data to another location before returning. The other location could for example be a file in the clients file system.

Parameters

parameter	user provided parameter
buffer	pointer to the buffer containing the received data
bytesRead	number of bytes available in the buffer

Returns

true if the client implementation shall continue to download data false if the download should be stopped. E.g. if the file cannot be stored client side due to missing resources.

IedConnection_FileDirectoryEntryHandler

typedef bool(* IedConnection_FileDirectoryEntryHandler) (uint32_t invokeId, void *parameter, IedClientError err, char *filename, uint32_t size, uint64_t lastModfified, bool moreFollows)

Callback handler for the get file directory service.

Will be called once for each file directory entry and after the last entry with moreFollows = false to indicate to indicate that no more data will follow. In case of an error the callback will be called with err != IED_ERROR_OK and moreFollows = false.

Callback handler for the get file directory service

Will be called once for each file directory entry and after the last entry with filename = NULL to indicate with moreFollows set to true if more data is available at the server (can only happen when using the IedConnection_getFileDirectoryAsyncEx function). In case of an error the callback will be called with err != IED_ERROR_OK and moreFollows = false.

Parameters

invokeId	invoke ID of the request
parameter	user provided parameter
err	error code in case of a problem, otherwise IED_ERROR_OK
filename	the filename of the current file directory entry or NULL if no more entries are available
size	the file size in byte of the current file directory entry
lastModified	the last modified timestamp of the current file directory entry

Returns

return false when the request has to be stopped (no further callback invokations), true otherwise

IedConnection_GetFileAsyncHandler

typedef bool(* IedConnection_GetFileAsyncHandler) (uint32_t invokeId, void *parameter, IedClientError err, uint32_t originalInvokeId, uint8_t *buffer, uint32_t bytesRead, bool moreFollows)

User provided handler to receive the data of the asynchronous GetFile request.

This handler will be invoked whenever the clients receives a data block from the server. The API user has to copy the data to another location before returning. The other location could for example be a file in the clients file system. When the last data block is received the moreFollows parameter will be set to false.

Parameters

invokeId	invoke ID of the message containing the received data
parameter	user provided parameter passed to the callback
err	error code in case of an error or IED_ERROR_OK
originalInvokeId	the invoke ID of the original (first) request. This is usually the request to open the file.
buffer	the buffer that contains the received file data
bytesRead	the number of bytes read into the buffer
moreFollows	indicates that more file data is following

Returns

true, continue the file download when moreFollows is true, false, stop file download

Function Documentation

FileDirectoryEntry_create()

LIB61850_API FileDirectoryEntry FileDirectoryEntry_create	(	const char *	fileName,
		uint32_t	fileSize,
		uint64_t	lastModified
	)

Deprecated:

Will be removed from API

FileDirectoryEntry_destroy()

LIB61850_API void FileDirectoryEntry_destroy

(

FileDirectoryEntry

self

)

Destroy a FileDirectoryEntry object (free all resources)

NOTE: Usually is called as a parameter of the LinkedList_destroyDeep function.

Parameters

self	the FileDirectoryEntry object

FileDirectoryEntry_getFileName()

LIB61850_API const char* FileDirectoryEntry_getFileName

(

FileDirectoryEntry

self

)

Get the name of the file.

Parameters

self	the FileDirectoryEntry object

Returns

name of the file as null terminated string

FileDirectoryEntry_getFileSize()

LIB61850_API uint32_t FileDirectoryEntry_getFileSize

(

FileDirectoryEntry

self

)

Get the file size in bytes.

Parameters

self	the FileDirectoryEntry object

Returns

size of the file in bytes, or 0 if file size is unknown

FileDirectoryEntry_getLastModified()

LIB61850_API uint64_t FileDirectoryEntry_getLastModified

(

FileDirectoryEntry

self

)

Get the timestamp of last modification of the file.

Parameters

self	the FileDirectoryEntry object

Returns

UTC timestamp in milliseconds

IedConnection_deleteFile()

LIB61850_API void IedConnection_deleteFile	(	IedConnection	self,
		IedClientError *	error,
		const char *	fileName
	)

Implementation of the DeleteFile ACSI service.

Delete a file at the server.

Parameters

self	the connection object
error	the error code if an error occurs
fileName	the name of the file to delete

IedConnection_deleteFileAsync()

LIB61850_API uint32_t IedConnection_deleteFileAsync	(	IedConnection	self,
		IedClientError *	error,
		const char *	fileName,
		IedConnection_GenericServiceHandler	handler,
		void *	parameter
	)

Implementation of the DeleteFile ACSI service - asynchronous version.

Delete a file at the server.

Parameters

self	the connection object
error	the error code if an error occurs
fileName	the name of the file to delete
handler	callback handler that is called when the obtain file response has been received
parameter	user provided callback parameter

IedConnection_getFile()

LIB61850_API uint32_t IedConnection_getFile	(	IedConnection	self,
		IedClientError *	error,
		const char *	fileName,
		IedClientGetFileHandler	handler,
		void *	handlerParameter
	)

Implementation of the GetFile ACSI service.

Download a file from the server.

Parameters

self	the connection object
error	the error code if an error occurs
fileName	the name of the file to be read from the server

Returns

number of bytes received

IedConnection_getFileAsync()

LIB61850_API uint32_t IedConnection_getFileAsync	(	IedConnection	self,
		IedClientError *	error,
		const char *	fileName,
		IedConnection_GetFileAsyncHandler	handler,
		void *	parameter
	)

Implementation of the GetFile ACSI service - asynchronous version.

Download a file from the server.

NOTE: This function can cause several request messages to be sent until the complete file is received or the file transfer is canceled. It allocates a background task and an outstanding call slot.

Parameters

self	the connection object
error	the error code if an error occurs
fileName	the name of the file to be read from the server
hander	callback handler that is called for each received data or error message
parameter	user provided callback parameter

Returns

invokeId of the first sent request

IedConnection_getFileDirectory()

LIB61850_API LinkedList IedConnection_getFileDirectory	(	IedConnection	self,
		IedClientError *	error,
		const char *	directoryName
	)

returns the directory entries of the specified file directory.

Requires the server to support file services.

NOTE: the returned linked list has to be freed by the user. You can user the following statement to free the list of directory entries:

LinkedList_destroyDeep(fileNames, (LinkedListValueDeleteFunction) FileDirectoryEntry_destroy);

where fileNames is the return value of this function.

Parameters

self	the connection object
error	the error code if an error occurs
directoryName	the name of the directory or NULL to get the entries of the root directory

Returns

the list of directory entries. The return type is a LinkedList with FileDirectoryEntry elements

IedConnection_getFileDirectoryAsyncEx()

LIB61850_API uint32_t IedConnection_getFileDirectoryAsyncEx	(	IedConnection	self,
		IedClientError *	error,
		const char *	directoryName,
		const char *	continueAfter,
		IedConnection_FileDirectoryEntryHandler	handler,
		void *	parameter
	)

Get file directory (single request) - asynchronous version.

The provided handler will be called for each received file directory entry.

NOTE: This will only cause a single MMS request. When the resulting file directory doesn't fit into a single MMS PDU another request has to be sent indicating a continuation point with the continueAfter parameter.

Parameters

self	the connection object
error	the error code if an error occurs
directoryName	the name of the directory or NULL to get the entries of the root directory
continueAfter	last received filename to continue after, or NULL for the first request
handler	the callback handler
parameter	user provided callback parameter

Returns

the invokeId of the first file directory request

IedConnection_getFileDirectoryEx()

LIB61850_API LinkedList IedConnection_getFileDirectoryEx	(	IedConnection	self,
		IedClientError *	error,
		const char *	directoryName,
		const char *	continueAfter,
		bool *	moreFollows
	)

returns the directory entries of the specified file directory returned by a single file directory request.

This function will only create a single request and the result may only be the directory that fits into a single MMS PDU. If the server contains more directory entries, this will be indicated by setting the moreFollows variable (if provided by the caller). If the directory entry does not fit into a single MMS PDU the next part of the directory list can be requested by setting the continueAfter parameter with the value of the last filename of the received list.

Requires the server to support file services.

NOTE: the returned linked list has to be freed by the user. You can user the following statement to free the list of directory entries:

LinkedList_destroyDeep(fileNames, (LinkedListValueDeleteFunction) FileDirectoryEntry_destroy);

where fileNames is the return value of this function.

Parameters

self	the connection object
error	the error code if an error occurs
directoryName	the name of the directory or NULL to get the entries of the root directory
continueAfter	last received filename to continue after, or NULL for the first request
moreFollows	if provided by the caller (non NULL) the function will indicate if more directory entries are available.

Returns

the list of directory entries. The return type is a LinkedList with FileDirectoryEntry elements

IedConnection_setFile()

LIB61850_API void IedConnection_setFile	(	IedConnection	self,
		IedClientError *	error,
		const char *	sourceFilename,
		const char *	destinationFilename
	)

Implementation of the SetFile ACSI service.

Upload a file to the server. The file has to be available in the local VMD filestore.

Parameters

self	the connection object
error	the error code if an error occurs
sourceFilename	the filename of the local (client side) file
destinationFilename	the filename of the remote (service side) file

IedConnection_setFileAsync()

LIB61850_API uint32_t IedConnection_setFileAsync	(	IedConnection	self,
		IedClientError *	error,
		const char *	sourceFilename,
		const char *	destinationFilename,
		IedConnection_GenericServiceHandler	handler,
		void *	parameter
	)

Implementation of the SetFile ACSI service - asynchronous version.

Upload a file to the server. The file has to be available in the local VMD filestore.

Parameters

self	the connection object
error	the error code if an error occurs
sourceFilename	the filename of the local (client side) file
destinationFilename	the filename of the remote (service side) file
handler	callback handler that is called when the obtain file response has been received
parameter	user provided callback parameter

IedConnection_setFilestoreBasepath()

LIB61850_API void IedConnection_setFilestoreBasepath	(	IedConnection	,
		const char *	basepath
	)

Set the virtual filestore basepath for the setFile service.

All external file service accesses will be mapped to paths relative to the base directory. NOTE: This function is only available when the CONFIG_SET_FILESTORE_BASEPATH_AT_RUNTIME option in stack_config.h is set.

Parameters

self	the connection object
basepath	the new virtual filestore basepath