Opened 5 years ago

Closed 5 years ago

#257 closed enhancement (fixed)

There should be a common interface for protocol registration

Reported by: ph3-der-loewe Owned by: ph3-der-loewe
Priority: medium Milestone: RoarAudio major release 1.0
Component: libroar and friends Version: 1.0beta4
Keywords: plugins Cc:
Architecture: Compiler:
Difficulty: normal Kernel:
Operating System: Parent Tickets: #256, #261, #267
Patch attached: no Protocol:
Sound driver: Topic: Cleanup

Description (last modified by 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:

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).

Subtickets

Change History (14)

comment:1 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

Added some ideas about the structure to be used.

comment:2 Changed 5 years ago by 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.

comment:3 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

some more ideas

comment:4 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

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

comment:5 Changed 5 years ago by ph3-der-loewe

  • Parent Tickets changed from 256 to 256, 261

comment:6 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

added protocol instance parameters.

comment:7 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

Added WAIT_NOTIFY flag to status type.

comment:8 Changed 5 years ago by ph3-der-loewe

  • Parent Tickets changed from 256, 261 to 256, 261, 267

comment:9 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)

Added flags.

comment:10 Changed 5 years ago by ph3-der-loewe

  • Owner set to ph3-der-loewe
  • Status changed from new to accepted

comment:11 Changed 5 years ago by ph3-der-loewe

  • Resolution set to fixed
  • Status changed from accepted to closed

comment:12 Changed 5 years ago by ph3-der-loewe

  • Version changed from current to 1.0beta4

comment:13 Changed 5 years ago by ph3-der-loewe

  • Description modified (diff)
  • Resolution fixed deleted
  • Status changed from closed to reopened

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).

comment:14 Changed 5 years ago by ph3-der-loewe

  • Resolution set to fixed
  • Status changed from reopened to closed
Note: See TracTickets for help on using tickets.