id summary reporter owner description type status priority milestone component version resolution keywords cc arch compiler difficulty kernel operatingsystem parents patch protocol sounddrv topic 257 There should be a common interface for protocol registration ph3-der-loewe 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)." enhancement closed medium RoarAudio major release 1.0 libroar and friends 1.0beta4 fixed plugins normal 256, 261, 267 0 Cleanup