Describes the callback functions that should be implemented by an auth module. More...

Data Fields
int(*	auth_check_read )(session_t session, object_t obj, char *requested_name)

int(*	auth_check_update )(session_t session, object_t obj, char *data)

int(*	auth_check_write )(session_t session, object_t obj, char *requested_name)

int(*	auth_check_write_extended )(session_t session, object_t obj, char requested_name, int field_count, string_pair_t fields, char *contrib_id)

int(*	auth_discard_object )(session_t session, object_t obj)

void(*	auth_exit )()

int(*	auth_free_object )(object_t *obj)

int(*	auth_free_user )(session_t *session)

void(*	auth_global_permission_update )(object_t obj, char key, int auth_map_size, auth_map_t *keyvalues, auth_perm_operation_t operation)

int(*	auth_http_request )(char user, char pass, http_method_t method, char *path)

int(*	auth_map_object )(session_t session, char requested_name, char name, char mapped, int *len)

int(*	auth_new_object )(object_t obj, object_t parent)

int(*	auth_new_user )(session_t session, char user, char *pass)

int(*	auth_request_object )(session_t session, object_t obj)

Detailed Description

Describes the callback functions that should be implemented by an auth module.

Examples:: exampleauth.c, and system.c.

Field Documentation

int(* _authfuncs::auth_check_read) (session_t *session, object_t *obj, char *requested_name)

Function called when a session requests read access to an object.

Parameters

session	- The RTTP session object
obj	- The RTTP object
requested_name	- The subject that is requested before any mappings got applied

Return values

AUTH_OK	- Authorisation is successful.
AUTH_DENY	- Authorisation is denied
AUTH_AGAIN	- If the Liberator has not yet received the value of an object, authorisation will be rerequested when the value is returned - see Content Based Permissioning.
AUTH_USER1...AUTH_USER5	- User defined return codes

This function is called when a user first requests updates for an object, the return value indicates whether the session should be permitted to receive updates for the object. The user that the session represents can be obtained by querying _session::user.

Read access is needed to receive data on an object.

Examples:: exampleauth.c.

int(* _authfuncs::auth_check_update) (session_t *session, object_t *obj, char *data)

This function enables the auth module to check permissioning for each individual update

Parameters

session	- The RTTP session object
obj	- The RTTP object
data	- The permissioning string for this update

Return values

AUTH_OK	- Authorisation is successful i.e. the session can receive this update
AUTH_DENY	- Authorisation is not successful i.e. the session cannot receive this update

Note: The currently works only for news headlines, and only if the sending DataSource application specifies per-update authorisation.; The permissioning data is limited to 32 characters (any additional characters will be truncated).

Examples:: exampleauth.c.

int(* _authfuncs::auth_check_write) (session_t *session, object_t *obj, char *requested_name)

Function called when a session requests write access to an object.

Parameters

session	- The RTTP session object
obj	- The RTTP object
requested_name	- The subject that is contributed to before any mappings got applied

Return values

AUTH_OK	- Authorisation is successful.
AUTH_DENY	- Authorisation is denied
AUTH_AGAIN	- If the Liberator has not yet received the value of an object, authorisation will be rerequested when the value is returned - see Content Based Permissioning.
AUTH_USER1...AUTH_USER5	- User defined return codes

This function is called when a user tries to either create or contribute to an object, the return value indicates whether the session should be permitted to perform the action. The user that the session represents can be obtained by querying _session::user.

Write access is needed to contribute to objects. To create an object you need write access to the directory (parent object) that the object is in.

Examples:: exampleauth.c.

int(* _authfuncs::auth_check_write_extended) (session_t *session, object_t *obj, char *requested_name, int field_count, string_pair_t *fields, char *contrib_id)

Function called when a session requests write access to an object. As auth_check_write, but additionally provides a list of field name/value pairs.

Parameters

session	- The RTTP session object
obj	- The RTTP object
requested_name	- The subject that is contributed to before any mappings got applied
field_count	- How many field are present in the update.
fields	- An array of field name/value pairs
contrib_id	- Contribution identifier.

Return values

AUTH_OK	- Authorisation is successful.
AUTH_DENY	- Authorisation is denied
AUTH_AGAIN	- If the auth module can not immmediately return a result, return this value and then callback later with the result using the event THREADS_AUTH_CHECKWRITE. Returning this value is only valid should the contrib_id parameter be non-null.
AUTH_USER1...AUTH_USER5	- User defined return codes

This function is called when a user tries to either create or contribute to an object, the return value indicates whether the session should be permitted to perform the action. The user that the session represents can be obtained by querying _session::user.

Write access is needed to contribute to objects. To create an object you need write access to the directory (parent object) that the object is in.

int(* _authfuncs::auth_discard_object) (session_t *session, object_t *obj)

Function that is called when a session is no longer looking at an object.

Parameters

session	- The RTTP session object
obj	- The RTTP object

Returns: ignored

This function typically requires no further action as the return value is not used. This function can be used to provide extra logging, each call to it will match a previous _authfuncs::auth_rqeuest_object() call

Examples:: exampleauth.c.

void(* _authfuncs::auth_exit) ()

The function is called when the Liberator is shutting down

Examples:: exampleauth.c.

int(* _authfuncs::auth_free_object) (object_t *obj)

Function called when an object is about to be deleted.

Parameters

obj	- The RTTP object

Return values

AUTH_OK - Unused.

This function should be used to release any resources used by the object (eg those that may have be initialised with _authfuncs::auth_new_object()

Examples:: exampleauth.c.

int(* _authfuncs::auth_free_user) (session_t *session)

Function called when a session is about to be terminated

Parameters

session - The RTTP Session object

Return values

AUTH_OK - Unused

This function should free up any resources allocated by the auth module for this session

Examples:: exampleauth.c.

void(* _authfuncs::auth_global_permission_update) (object_t *obj, char *key, int auth_map_size, auth_map_t *keyvalues, auth_perm_operation_t operation)

This function enables the auth module to intercept permissioning updates

Parameters

obj	- The RTTP object
key	- The Permission Key string for this update
auth_map_size	- The number of entries in the auth_map
keyvalues	- An array of Key/Value pairs for this Permission key
operation	- Operation to perform

int(* _authfuncs::auth_http_request) (char *user, char *pass, http_method_t method, char *path)

Function that is called when a restricted HTTP directory is accessed

Parameters

user	- The name of the user
pass	- The password or token supplied by the user.
method	- The HTTP method that was issued.
path	- The HTTP path

Return values

AUTH_OK	- Authorisation is successful.
AUTH_DENY	- Authorisation is denied.

This function enables this Auth Module to be used to allow users access to restricted HTTP directories. The directories are specified by add-authdir entries in the Caplin Liberator configuration file.

Examples:: exampleauth.c.

int(* _authfuncs::auth_map_object) (session_t *session, char *requested_name, char *name, char *mapped, int *len)

Function called when a session requests an object.

Parameters

session	- The RTTP session object.
requested_name	- The name of the object before mappings got applied
name	- The name of the object requested.
mapped	- A buffer to hold the new name.
len	- Length of name (number of characters).

Return values

AUTH_OK	- Mapping was successful.
AUTH_FALSE	- Mapping was unsuccessful.
AUTH_DELAYED	- Mapping is delayed.
AUTH_USER1...AUTH_USER5	- User defined return codes

This function can be used to deliver renamed objects to users without them seeing the new name.

The len parameter contains the length of the name when the function is called. If the name is mapped (and AUTH_OK returned), the len parameter will then contain the length of the new name.

Examples:: exampleauth.c.

int(* _authfuncs::auth_new_object) (object_t *obj, object_t *parent)

Function called when a new object is created.

Parameters

obj	- The RTTP object
parent	- The parent object

Return values

AUTH_OK - Unused

This function can be used to attach any authorisation data specific to the object which can then be used by other callbacks

Examples:: exampleauth.c.

int(* _authfuncs::auth_new_user) (session_t *session, char *user, char *pass)

Function called to authenticate the user

Parameters

session	- The RTTP session object
user	- The name of the user

Return values

AUTH_OK	- Authentication is successful.
AUTH_INVALID_USER	- Username entered is invalid.
AUTH_INVALID_PASS	- Password entered is invalid.
AUTH_ACCT_EXPIRED	- User's account has expired.
AUTH_USER_LC_EXCEEDED	- User's total number of permitted licences has been exceeded.
AUTH_SITE_LC_EXCEEDED	- Site's total number of permitted licences has been exceeded.
AUTH_ERROR	- An error occurred during authentication.
AUTH_DELAYED	- Authentication is delayed. See callback parameter in auth_mod_init()

Examples:: exampleauth.c.

int(* _authfuncs::auth_request_object) (session_t *session, object_t *obj)

Function that is called when a session first looks at an object.

Parameters

session	- The RTTP session object
obj	- The RTTP object

Returns: ignored

This function typically requires no further action as the return value is not used. This function can be used to provide extra logging, each call to it will be match by a later _authfuncs::auth_discard_object() call

Examples:: exampleauth.c.

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

rttpd.h

Data Fields

Detailed Description

Field Documentation