There should be a common interface for protocol registration

[ph3-der-loewe]

Task

There should be a common interface for protocol registrations.
This is useful for plugins providing host independent services via network and as general cleanup to have a more standardized interface for the applications currently providing plugin loadable protocols.

Currently the following tools are known to me providing this:

• roard
• rpld
• SavannahIce?

The following tools may add support if it is easy to be added (maybe with plugincontainer support):

• roarpluginrunner
• ices2 (maybe in private branch)
• icecast (maybe in private branch)

Draft for data structures

The Protocol registration block/struct

Member Name	Type/Return? type	Description
proto	const int	The protocol ID
description	const char *	The protocol description in a lion readable way
flags	const int	Flags. Must be zero.
set_proto	func/int	Callback called when new client connects using this protocol
unset_proto	func/int	Callback called when client is disconnected from this protocol
handle	func/int	Callback called when where are new data to be handled
flush	func/int	Callback called when output data can be send to the client
flushed	func/int	Callback called when all output has been flushed
status	func/status	Callback called to get client status for flow control

set_proto and unset_proto are called this way (not new_client and close_client or similar) because the socket may be used before or after this. An example is EXEC for clients when a client changes the protocol it is using.

flush and flushed is only used when obuffer (see definition of function type) is used to store data ready to be send to the client. Using this allows easy non-blocking operations. The host will default to an internal flush function if none is given (set NULL). This allows the protocol to just append output to obuffer using the normal Roar Buffer functions and not need to care for buffering the output itself.

The function type

The function type above is a pointer to a function with the following arguments:

Argument	Type	Description
client	int	The client ID
vio	struct roar_vio_calls *	The VIO Object the client is connected to
obuffer	struct roar_buffer	The Output buffer (see above)
userdata	void	Pointer for the protocol to store per-client private data
protopara	const struct roar_keyval *	Parameter array passed to the protocol. This is per listen socket. Can be NULL.
protoparalen	ssize_t	This is the length of para. Is -1 if para is NULL. Can be -1 if para is not NULL (in this case para ends with a key set to NULL).
pluginpara	struct roar_dl_librarypara *	This is the parameter object for the current plugin if any. If no such object is existing or this is not a plugin based implementation the parameter object is NULL. The refcount is set in a way that the function does not need to care expect of they store the object in some storage with a lifetime other than the scope of the function. In this case they need to ref it before and unref when deleting the pointer from that storage.

When the client is forcefully disconnected by the protocol and obuffer is not NULL it is undefined whether the data is flushed to the client or just discarded.

When *userdata is not NULL in the moment the client is deleted it is freed using roar_mm_free(). If freeing with roar_mm_free() is wrong or the object has complex structure and needs to be freed by a special function it must be freed in unset_proto and *userdata must be set NULL.

The Client status type

This should be an integer type used to store flags.

Flag	Name	Description
0x0001	RX_READY	The protocol implementation is ready to read more data from the client
0x0002	TX_READY	The client is ready to read more data from the server.
0x0004	WAIT_NOTIFY	The client is currently waiting for an asynchronous event. The type of this event is out of scope of this specification. It may be a timer, a notify API event or some other kind of asynchronous event.

Callbacks may be called even if the status callback would return that the client is not ready for the given operation. The callback have to return without doing something. The callback must return without error or setting the error value correctly for the situation (e.g. ROAR_ERROR_AGAIN).

[ph3-der-loewe]

Added some ideas about the structure to be used.

[ph3-der-loewe]

The protocol registration struct should be registered using roar_dl_register_fn(). Initial Version number should be zero. fn is to be set to ROAR_DL_FN_PROTO. subtype needs to be defined.

[ph3-der-loewe]

some more ideas

[ph3-der-loewe]

Updated formating and become more precise to the way the status type should work.

[ph3-der-loewe]

added protocol instance parameters.

[ph3-der-loewe]

Added WAIT_NOTIFY flag to status type.

[ph3-der-loewe]

Added flags.

[ph3-der-loewe]

The current interface doesn't allow access to the plugin's parameter handle (if any). The function prototype needs to be changed for this. I updated the description with an idea for me.

I keep the version as it should be fixed within this version. This should be considered an objection against the current pre-release (1.0beta4-pr0).