| | 13 | |
| | 14 | == Draft for data structures == |
| | 15 | === The Protocol registration block/struct === |
| | 16 | ||= Member Name =||= Type/Return type =||= Description =|| |
| | 17 | ||proto ||const int ||The protocol ID || |
| | 18 | ||description ||const char * ||The protocol description in a lion readable way|| |
| | 19 | ||set_proto ||func/int ||Callback called when new client connects using this protocol || |
| | 20 | ||unset_proto ||func/int ||Callback called when client is disconnected from this protocol || |
| | 21 | ||handle ||func/int ||Callback called when where are new data to be handled || |
| | 22 | ||flush ||func/int ||Callback called when output data can be send to the client || |
| | 23 | ||flushed ||func/int ||Callback called when all output has been flushed || |
| | 24 | ||status ||func/status ||Callback called to get client status for flow control || |
| | 25 | |
| | 26 | 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. |
| | 27 | |
| | 28 | 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. |
| | 29 | |
| | 30 | === The function type === |
| | 31 | The function type above is a pointer to a function with the following arguments: |
| | 32 | ||= Argument =||= Type =||= Description =|| |
| | 33 | ||client ||int ||The client ID || |
| | 34 | ||vio ||struct roar_vio_calls * ||The VIO Object the client is connected to || |
| | 35 | ||obuffer ||struct roar_buffer ** ||The Output buffer (see above) || |
| | 36 | ||userdata ||void ** ||Pointer for the protocol to store per-client private data|| |
| | 37 | |
| | 38 | 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. |
| | 39 | |
| | 40 | 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. |
| | 41 | |
| | 42 | === The Client status type === |
| | 43 | This type has to be defined. |
