A Handler is a datatype for accessing data. More...

#include <handler.h>

Collaboration diagram for Handler:

Public Member Functions
void	InitialiseHandler (Handler const handler_p, bool(init_fn)(struct Handler handler_p, const User user_p), bool(match_fn)(struct Handler handler_p, const DataResource resource_p), const char (get_protocol_fn)(struct Handler handler_p), const char (get_name_fn)(struct Handler handler_p), const char (get_description_fn)(struct Handler handler_p), bool(open_fn)(struct Handler handler_p, DataResource resource_p, MEM_FLAG resource_mem, const char const mode_s), size_t(read_fn)(struct Handler handler_p, void buffer_p, const size_t length), size_t(write_fn)(struct Handler handler_p, const void buffer_p, const size_t length), bool(seek_fn)(struct Handler handler_p, long offset, int whence), bool(close_fn)(struct Handler handler_p), HandlerStatus(status_fn)(struct Handler handler_p), bool(file_info_fn)(struct Handler handler_p, FileInformation info_p), void(free_handler_fn)(struct Handler *handler_p))
	Initialise a Handler from a loaded Plugin. More...

bool	InitHandler (struct Handler handler_p, const User user_p)
	Initialise a Handler ready for use. More...

bool	OpenHandler (struct Handler handler_p, DataResource resource_p, MEM_FLAG resource_mem, const char *const mode_s)
	Open a Resource with the Handler. More...

size_t	ReadFromHandler (struct Handler handler_p, void buffer_p, const size_t length)
	Read data from a Handler into a buffer. More...

size_t	WriteToHandler (struct Handler handler_p, const void buffer_p, const size_t length)
	Write data from a buffer into a Handler. More...

bool	SeekHandler (struct Handler *handler_p, size_t offset, int whence)
	Move a Handler to a new position in its stream. More...

bool	CloseHandler (struct Handler *handler_p)
	Close a Handler. More...

bool	IsHandlerForResource (struct Handler handler_p, const DataResource resource_p)
	Determine if the Handler is designed for a given Resource. More...

const char *	GetHandlerName (struct Handler *handler_p)
	Get the name of a Handler. More...

const char *	GetHandlerDescription (struct Handler *handler_p)
	Get the description of a Handler. More...

const char *	GetHandlerProtocol (struct Handler *handler_p)
	Get the protocol of a Handler. More...

HandlerStatus	GetHandlerStatus (struct Handler *handler_p)
	Get the HandlerStatus of a Handler. More...

bool	CalculateFileInformationFromHandler (struct Handler handler_p, FileInformation info_p)
	Calculate the FileInformation for the current Resource in use by a Handler. More...

void	FreeHandler (struct Handler *handler_p)
	Free a Handler. More...

Data Fields
struct Plugin *	ha_plugin_p
	The platform-specific plugin that the code for the Client is stored in. More...

bool(*	ha_init_fn )(struct Handler handler_p, const User user_p)
	Initialise a Handler ready for use. More...

bool(*	ha_match_fn )(struct Handler handler_p, const DataResource resource_p)
	Determine if the Handler is designed for a given Resource. More...

const char (	ha_get_protocol_fn )(struct Handler *handler_p)
	Get the protocol of a Handler. More...

const char (	ha_get_name_fn )(struct Handler *handler_p)
	Get the name of a Handler. More...

const char (	ha_get_description_fn )(struct Handler *handler_p)
	Get the description of a Handler. More...

bool(*	ha_open_fn )(struct Handler handler_p, DataResource resource_p, MEM_FLAG resource_mem, const char *const mode_s)
	Open a Resource with the Handler. More...

size_t(*	ha_read_fn )(struct Handler handler_p, void buffer_p, const size_t length)
	Read data from a Handler into a buffer. More...

size_t(*	ha_write_fn )(struct Handler handler_p, const void buffer_p, const size_t length)
	Write data from a buffer into a Handler. More...

bool(*	ha_seek_fn )(struct Handler *handler_p, long offset, int whence)
	Move a Handler to a new position in its stream. More...

bool(*	ha_close_fn )(struct Handler *handler_p)
	Close a Handler. More...

HandlerStatus(*	ha_status_fn )(struct Handler *handler_p)
	Get the HandlerStatus of a Handler. More...

bool(*	ha_file_info_fn )(struct Handler handler_p, FileInformation info_p)
	Calculate the FileInformation for the current Resource in use by a Handler. More...

void(*	ha_free_handler_fn )(struct Handler *handler_p)
	Free a Handler. More...

DataResource *	ha_resource_p
	The current Resource for this Handler. More...

MEM_FLAG	ha_resource_mem
	The MEM_FLAG for the Handler's Resource. More...

Detailed Description

A Handler is a datatype for accessing data.

It is an abstraction of the common data input/output operations, e.g., opening and closing files, reading and writing data, etc. Any Grassroots component can use any Handler to access data without having to worry about the internals. So just by loading the appropriate Handler, a task can read data from a file, and iRODS data object, a webpage, etc. simply by using the Handler API.

Member Function Documentation

◆ InitialiseHandler()

void InitialiseHandler	(	Handler *const	handler_p,
		bool()(struct Handler handler_p, const User *user_p)	init_fn,
		bool()(struct Handler handler_p, const DataResource *resource_p)	match_fn,
		const char ()(struct Handler *handler_p)	get_protocol_fn,
		const char ()(struct Handler *handler_p)	get_name_fn,
		const char ()(struct Handler *handler_p)	get_description_fn,
		bool()(struct Handler handler_p, DataResource resource_p, MEM_FLAG resource_mem, const char const mode_s)	open_fn,
		size_t()(struct Handler handler_p, void *buffer_p, const size_t length)	read_fn,
		size_t()(struct Handler handler_p, const void *buffer_p, const size_t length)	write_fn,
		bool()(struct Handler handler_p, long offset, int whence)	seek_fn,
		bool()(struct Handler handler_p)	close_fn,
		HandlerStatus()(struct Handler handler_p)	status_fn,
		bool()(struct Handler handler_p, FileInformation *info_p)	file_info_fn,
		void()(struct Handler handler_p)	free_handler_fn
	)

Initialise a Handler from a loaded Plugin.

Parameters

handler_p	The Handler to initialise.
init_fn	The callback function to use for the Handler's ha_init_fn function.

See also: ha_init_fn

Parameters

match_fn The callback function to use for the Handler's ha_match_fn function.

See also: ha_match_fn

Parameters

get_protocol_fn The callback function to use for the Handler's ha_get_protocol_fn function.

See also: ha_get_protocol_fn

Parameters

get_name_fn The callback function to use for the Handler's ha_get_name_fn function.

See also: ha_get_name_fn

Parameters

get_description_fn The callback function to use for the Handler's ha_get_description_fn function.

See also: ha_get_description_fn

Parameters

open_fn The callback function to use for the Handler's ha_open_fn function.

See also: ha_open_fn

Parameters

read_fn The callback function to use for the Handler's ha_read_fn function.

See also: ha_read_fn

Parameters

write_fn The callback function to use for the Handler's ha_write_fn function.

See also: ha_write_fn

Parameters

seek_fn The callback function to use for the Handler's ha_seek_fn function.

See also: ha_seek_fn

Parameters

close_fn The callback function to use for the Handler's ha_close_fn function.

See also: ha_close_fn

Parameters

status_fn The callback function to use for the Handler's ha_status_fn function.

See also: ha_status_fn

Parameters

file_info_fn The callback function to use for the Handler's ha_file_info_fn function.

See also: ha_file_info_fn

Parameters

free_handler_fn The callback function to use for the Handler's ha_free_handler_fn function.

See also: ha_free_handler_fn

◆ InitHandler()

bool InitHandler	(	struct Handler *	handler_p,
		const User *	user_p
	)

Initialise a Handler ready for use.

This is for when the Handler may need some custom initialisation e.g. permissions to be used.

Parameters

handler_p	The Handler to initialise.
user_p	The current user's details. This can be `NULL`.

Returns: true upon success, false upon failure.

See also: ha_init_fn

◆ OpenHandler()

bool OpenHandler	(	struct Handler *	handler_p,
		DataResource *	resource_p,
		MEM_FLAG	resource_mem,
		const char *const	mode_s
	)

Open a Resource with the Handler.

Parameters

handler_p	The Handler to use
resource_p	The Resource to use
resource_mem	How the Handler will treat the Resource when the Handler is freed.
mode_s	The mode to open with. This is the same as the mode used with the standard c library fopen.

Returns: true upon success, false upon failure.

See also: ha_open_fn

◆ ReadFromHandler()

size_t ReadFromHandler	(	struct Handler *	handler_p,
		void *	buffer_p,
		const size_t	length
	)

Read data from a Handler into a buffer.

The data will be read from the current position of the Handler within its stream.

Parameters

handler_p	The Handler to read from.
buffer_p	The buffer to save the data into.
length	The number of bytes to read.

Returns: The number of bytes that were read.

◆ WriteToHandler()

size_t WriteToHandler	(	struct Handler *	handler_p,
		const void *	buffer_p,
		const size_t	length
	)

Write data from a buffer into a Handler.

The data will be written to the current position of the Handler within its stream.

Parameters

handler_p	The Handler to write to.
buffer_p	The buffer to read the data from.
length	The number of bytes to write.

Returns: The number of bytes that were written.

◆ SeekHandler()

bool SeekHandler	(	struct Handler *	handler_p,
		size_t	offset,
		int	whence
	)

Move a Handler to a new position in its stream.

This is equivalent to fseek in the standard c library.

Parameters

handler_p	The Handler to alter.
offset	The new position.
whence	The reference position to use. These are the constants defined in <stdio.h> SEEK_SET: Start of the stream. SEEK_CUR: Current position in the stream. SEEK_END: End of the stream.

Returns: true upon success, false upon failure.

◆ CloseHandler()

bool CloseHandler ( struct Handler * handler_p )

Close a Handler.

Parameters

handler_p The Handler to close.

Returns: true upon success, false upon failure.

◆ IsHandlerForResource()

bool IsHandlerForResource	(	struct Handler *	handler_p,
		const DataResource *	resource_p
	)

Determine if the Handler is designed for a given Resource.

Parameters

handler_p	The Handler to check.
resource_p	The Resource to check the Handler with.

Returns: true if the Handler is for the Resource, false false otherwise.

◆ GetHandlerName()

const char * GetHandlerName ( struct Handler * handler_p )

Get the name of a Handler.

Parameters

handler_p The Handler to get the name of.

Returns: The name of the Handler.

◆ GetHandlerDescription()

const char * GetHandlerDescription ( struct Handler * handler_p )

Get the description of a Handler.

Parameters

handler_p The Handler to get the description of.

Returns: The description of the Handler.

◆ GetHandlerProtocol()

const char * GetHandlerProtocol ( struct Handler * handler_p )

Get the protocol of a Handler.

Parameters

handler_p The Handler to get the protocol of.

Returns: The protocol of the Handler.

See also: PROTOCOL_FILE; PROTOCOL_IRODS; PROTOCOL_HTTP

◆ GetHandlerStatus()

HandlerStatus GetHandlerStatus ( struct Handler * handler_p )

Get the HandlerStatus of a Handler.

Parameters

handler_p The Handler to get the HandlerStatus of.

Returns: The HandlerStatus

◆ CalculateFileInformationFromHandler()

bool CalculateFileInformationFromHandler	(	struct Handler *	handler_p,
		FileInformation *	info_p
	)

Calculate the FileInformation for the current Resource in use by a Handler.

Parameters

handler_p	The Handler to query.
info_p	Pointer to where the FileInformation will be stored upon success.

Returns: true upon success, false upon failure.

◆ FreeHandler()

void FreeHandler ( struct Handler * handler_p )

Free a Handler.

The Handler will be closed if needed and then freed.

Parameters

handler_p The Handler to free.

Field Documentation

◆ ha_plugin_p

struct Plugin* ha_plugin_p

The platform-specific plugin that the code for the Client is stored in.

◆ ha_init_fn

bool(* ha_init_fn) (struct Handler *handler_p, const User *user_p)

Initialise a Handler ready for use.

This is for when the Handler may need some custom initialisation e.g. permissions to be used.

Parameters

handler_p	This Handler.
user_p	Any custom credentials or configuration values. This can be `NULL`.

Returns: true upon success, false upon failure.

◆ ha_match_fn

bool(* ha_match_fn) (struct Handler *handler_p, const DataResource *resource_p)

Determine if the Handler is designed for a given Resource.

Parameters

handler_p	This Handler.
resource_p	The Resource to check the Handler with.

Returns: true if the Handler is for the Resource, false false otherwise.

◆ ha_get_protocol_fn

const char*(* ha_get_protocol_fn) (struct Handler *handler_p)

Get the protocol of a Handler.

Parameters

handler_p This Handler.

Returns: The protocol of the Handler.

See also: PROTOCOL_FILE; PROTOCOL_IRODS; PROTOCOL_HTTP

◆ ha_get_name_fn

const char*(* ha_get_name_fn) (struct Handler *handler_p)

Get the name of a Handler.

Parameters

handler_p This Handler.

Returns: The name of the Handler.

◆ ha_get_description_fn

const char*(* ha_get_description_fn) (struct Handler *handler_p)

Get the description of a Handler.

Parameters

handler_p This Handle.

Returns: The description of the Handler.

◆ ha_open_fn

bool(* ha_open_fn) (struct Handler *handler_p, DataResource *resource_p, MEM_FLAG resource_mem, const char *const mode_s)

Open a Resource with the Handler.

Parameters

handler_p	This Handler.
resource_p	The Resource to use.
resource_mem	How the Handler will treat the Resource when the Handler is freed.
mode_s	The mode to open with. This is the same as the mode used with the standard c library fopen.

Returns: true upon success, false upon failure.

◆ ha_read_fn

size_t(* ha_read_fn) (struct Handler *handler_p, void *buffer_p, const size_t length)

Read data from a Handler into a buffer.

The data will be read from the current position of the Handler within its stream.

Parameters

handler_p	This Handler.
buffer_p	The buffer to save the data into.
length	The number of bytes to read.

Returns: The number of bytes that were read.

◆ ha_write_fn

size_t(* ha_write_fn) (struct Handler *handler_p, const void *buffer_p, const size_t length)

Write data from a buffer into a Handler.

The data will be written to the current position of the Handler within its stream.

Parameters

handler_p	This Handler.
buffer_p	The buffer to read the data from.
length	The number of bytes to write.

Returns: The number of bytes that were written.

◆ ha_seek_fn

bool(* ha_seek_fn) (struct Handler *handler_p, long offset, int whence)

Move a Handler to a new position in its stream.

This is equivalent to fseek in the standard c library.

Parameters

handler_p	This Handler.
offset	The new position.
whence	The reference position to use. These are the constants defined in <stdio.h> SEEK_SET: Start of the stream. SEEK_CUR: Current position in the stream. SEEK_END: End of the stream.

Returns: true upon success, false upon failure.

◆ ha_close_fn

bool(* ha_close_fn) (struct Handler *handler_p)

Close a Handler.

Parameters

handler_p This Handler.

Returns: true upon success, false upon failure.

◆ ha_status_fn

HandlerStatus(* ha_status_fn) (struct Handler *handler_p)

Get the HandlerStatus of a Handler.

Parameters

handler_p This Handler.

Returns: The HandlerStatus

◆ ha_file_info_fn

bool(* ha_file_info_fn) (struct Handler *handler_p, FileInformation *info_p)

Calculate the FileInformation for the current Resource in use by a Handler.

Parameters

handler_p	This Handler.
info_p	Pointer to where the FileInformation will be stored upon success.

Returns: true upon success, false upon failure.

◆ ha_free_handler_fn

void(* ha_free_handler_fn) (struct Handler *handler_p)

Free a Handler.

The Handler will be closed if needed and then freed.

Parameters

handler_p This Handler.

◆ ha_resource_p

DataResource* ha_resource_p

The current Resource for this Handler.

◆ ha_resource_mem

MEM_FLAG ha_resource_mem

The MEM_FLAG for the Handler's Resource.

The documentation for this struct was generated from the following file:

handler.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ InitialiseHandler()

◆ InitHandler()

◆ OpenHandler()

◆ ReadFromHandler()

◆ WriteToHandler()

◆ SeekHandler()

◆ CloseHandler()

◆ IsHandlerForResource()

◆ GetHandlerName()

◆ GetHandlerDescription()

◆ GetHandlerProtocol()

◆ GetHandlerStatus()

◆ CalculateFileInformationFromHandler()

◆ FreeHandler()

Field Documentation

◆ ha_plugin_p

◆ ha_init_fn

◆ ha_match_fn

◆ ha_get_protocol_fn

◆ ha_get_name_fn

◆ ha_get_description_fn

◆ ha_open_fn

◆ ha_read_fn

◆ ha_write_fn

◆ ha_seek_fn

◆ ha_close_fn

◆ ha_status_fn

◆ ha_file_info_fn

◆ ha_free_handler_fn

◆ ha_resource_p

◆ ha_resource_mem