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

#include <handler.h>

Collaboration diagram for Handler:
[legend]

Public Member Functions

void InitialiseHandler (Handler *const handler_p, bool(*init_fn)(struct Handler *handler_p, const UserDetails *user_p), bool(*match_fn)(struct Handler *handler_p, const Resource *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, Resource *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 UserDetails *user_p)
 Initialise a Handler ready for use. More...
 
bool OpenHandler (struct Handler *handler_p, Resource *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 Resource *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 Pluginha_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 UserDetails *user_p)
 Initialise a Handler ready for use. More...
 
bool(* ha_match_fn )(struct Handler *handler_p, const Resource *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, Resource *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...
 
Resourceha_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.

Examples
long_running_service.c.

Member Function Documentation

◆ InitialiseHandler()

void InitialiseHandler ( Handler *const  handler_p,
bool(*)(struct Handler *handler_p, const UserDetails *user_p)  init_fn,
bool(*)(struct Handler *handler_p, const Resource *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, Resource *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_pThe Handler to initialise.
init_fnThe callback function to use for the Handler's ha_init_fn function.
See also
ha_init_fn
Parameters
match_fnThe callback function to use for the Handler's ha_match_fn function.
See also
ha_match_fn
Parameters
get_protocol_fnThe callback function to use for the Handler's ha_get_protocol_fn function.
See also
ha_get_protocol_fn
Parameters
get_name_fnThe callback function to use for the Handler's ha_get_name_fn function.
See also
ha_get_name_fn
Parameters
get_description_fnThe callback function to use for the Handler's ha_get_description_fn function.
See also
ha_get_description_fn
Parameters
open_fnThe callback function to use for the Handler's ha_open_fn function.
See also
ha_open_fn
Parameters
read_fnThe callback function to use for the Handler's ha_read_fn function.
See also
ha_read_fn
Parameters
write_fnThe callback function to use for the Handler's ha_write_fn function.
See also
ha_write_fn
Parameters
seek_fnThe callback function to use for the Handler's ha_seek_fn function.
See also
ha_seek_fn
Parameters
close_fnThe callback function to use for the Handler's ha_close_fn function.
See also
ha_close_fn
Parameters
status_fnThe callback function to use for the Handler's ha_status_fn function.
See also
ha_status_fn
Parameters
file_info_fnThe callback function to use for the Handler's ha_file_info_fn function.
See also
ha_file_info_fn
Parameters
free_handler_fnThe 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 UserDetails 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_pThe Handler to initialise.
user_pThe 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,
Resource resource_p,
MEM_FLAG  resource_mem,
const char *const  mode_s 
)

Open a Resource with the Handler.

Parameters
handler_pThe Handler to use
resource_pThe Resource to use
resource_memHow the Handler will treat the Resource when the Handler is freed.
mode_sThe 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_pThe Handler to read from.
buffer_pThe buffer to save the data into.
lengthThe 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_pThe Handler to write to.
buffer_pThe buffer to read the data from.
lengthThe 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_pThe Handler to alter.
offsetThe new position.
whenceThe 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_pThe Handler to close.
Returns
true upon success, false upon failure.

◆ IsHandlerForResource()

bool IsHandlerForResource ( struct Handler handler_p,
const Resource resource_p 
)

Determine if the Handler is designed for a given Resource.

Parameters
handler_pThe Handler to check.
resource_pThe 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_pThe 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_pThe 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_pThe 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_pThe 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_pThe Handler to query.
info_pPointer 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_pThe 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 UserDetails *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_pThis Handler.
user_pAny 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 Resource *resource_p)

Determine if the Handler is designed for a given Resource.

Parameters
handler_pThis Handler.
resource_pThe 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_pThis 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_pThis 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_pThis Handle.
Returns
The description of the Handler.

◆ ha_open_fn

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

Open a Resource with the Handler.

Parameters
handler_pThis Handler.
resource_pThe Resource to use.
resource_memHow the Handler will treat the Resource when the Handler is freed.
mode_sThe 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_pThis Handler.
buffer_pThe buffer to save the data into.
lengthThe 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_pThis Handler.
buffer_pThe buffer to read the data from.
lengthThe 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_pThis Handler.
offsetThe new position.
whenceThe 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_pThis 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_pThis 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_pThis Handler.
info_pPointer 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_pThis Handler.

◆ ha_resource_p

Resource* 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: