Opened 12 years ago
Last modified 12 years ago
#257 closed enhancement
There should be a common interface for protocol registration — at Version 3
Reported by: | ph3-der-loewe | Owned by: | |
---|---|---|---|
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 | |
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:
- 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 |
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 |
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.
- data can be read from client (rx ready)
- data can be send to the client (tx ready)
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 (3)
comment:1 Changed 12 years ago by ph3-der-loewe
- Description modified (diff)
comment:2 Changed 12 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.
Added some ideas about the structure to be used.