.. _protocols: 



Protocols
===========

Protocols are used to implement parsing and domain-specific functionality on
top of the raw I/O functionality provided by the :ref:`server <server>`.

.. admonition:: Implementing Protocols
   :class: admonition-info

   New protocols can be implemented by:

   - Providing an implementation for each of the
     :ref:`protocol callback <protocol callbacks>` types.
   - Populating a :c:struct:`ymo_proto` with some protocol metadata and
     filling out the :c:struct:`ymo_proto_vt` ``vtable``.
   - Providing a pointer to that structure in an invocation to
     :c:func:`ymo_server_create`.




.. _protocol callbacks: 



---------------------------------------------------------------
Callbacks
---------------------------------------------------------------



.. c:type:: ymo_proto_init_cb_t

   Protocol alloc/init callback type. [REQUIRED]
   
   Individual protocols provide functions which match this signature in order
   to provide allocation/initialization.
   
   :proto_data: private data for this protocol
   :server: the server issuing the callback
   
   Returns a status indicating protocol is ready for use
   
   be separated into two distinct callbacks.


   .. code-block:: c
      :caption: Definition
   
      typedef ymo_status_t (*ymo_proto_init_cb_t)(
              ymo_proto_t* proto, ymo_server_t* server);


.. c:type:: ymo_proto_cleanup_cb_t

   Protocol-level cleanup/dealloc callback type. [REQUIRED]
   
   Individual protocols provide a function which matches this signature in
   order to perform cleanup/deallocation.
   
   :proto: the protocol being destroyed
   :server: the server which is issuing the callback
   
   be separated into two distinct callbacks.


   .. code-block:: c
      :caption: Definition
   
      typedef void (*ymo_proto_cleanup_cb_t)(
              ymo_proto_t* proto, ymo_server_t* server);


.. c:type:: ymo_proto_conn_init_cb_t

   Protocol-level connection init callback. [OPTIONAL]
   
   Gives protocols a chance to do alloc/init per-connection data.
   
   :proto_data: the protocol data against which this is being invoked.
   :conn: the newly created connection object
   
   Returns per-connection protocol data (or NULL)


   .. code-block:: c
      :caption: Definition
   
      typedef void* (*ymo_proto_conn_init_cb_t)(
              void* proto_data, ymo_conn_t* conn);


.. c:type:: ymo_proto_conn_ready_cb_t

   Protocol-level connection ready callback. [OPTIONAL]
   
   Gives protocols a chance to do "on-open" style notification to user space.
   
   :proto_data: the protocol data against which this is being invoked.
   :conn: the newly created connection object
   :returns: per-connection protocol data (or NULL)


   .. code-block:: c
      :caption: Definition
   
      typedef ymo_status_t (*ymo_proto_conn_ready_cb_t)(
              void* proto_data, ymo_conn_t* conn, void* conn_data);


.. c:type:: ymo_proto_conn_cleanup_cb_t

   Protocol-level connection cleanup callback.
   
   Gives protocols a chance to do cleanup/deallocate per-connection data.
   
   :proto_data: the protocol data against which this is being invoked
   :conn: the connection object that's being destroyed
   :conn_data: the per-connection data associated with this connection


   .. code-block:: c
      :caption: Definition
   
      typedef void (*ymo_proto_conn_cleanup_cb_t)(
              void* proto_data,
              ymo_conn_t* conn,
              void* conn_data);


.. c:type:: ymo_proto_read_cb_t

   Protocol-level read callback. 


   .. code-block:: c
      :caption: Definition
   
      typedef ssize_t (*ymo_proto_read_cb_t)(
              void* proto_data,
              ymo_conn_t* conn,
              void* conn_data,
              char* buf_in,
              size_t len);


.. c:type:: ymo_proto_write_cb_t

   Protocol-level write callback. 


   .. code-block:: c
      :caption: Definition
   
      typedef ymo_status_t (*ymo_proto_write_cb_t)(
              void* proto_data,
              ymo_conn_t* conn,
              void* conn_data,
              int socket);


---------------------------------------------------------------
Types
---------------------------------------------------------------



.. c:struct:: ymo_proto_vt

   Protocol callback "vtable". 


   .. code-block:: c
      :caption: Definition
   
      struct ymo_proto_vt {
          ymo_proto_init_cb_t          init_cb;         /* Protocol init callback */
          ymo_proto_cleanup_cb_t       cleanup_cb;      /* Protocol cleanup callback */
          ymo_proto_conn_init_cb_t     conn_init_cb;    /* Client init callback */
          ymo_proto_conn_ready_cb_t    conn_ready_cb;   /* Client ready callback */
          ymo_proto_conn_cleanup_cb_t  conn_cleanup_cb; /* Client cleanup callback */
          ymo_proto_read_cb_t          read_cb;         /* Protocol read callback */
          ymo_proto_write_cb_t         write_cb;        /* Protocol write callback */
      };


.. c:struct:: ymo_proto

   Data structure used to define a single protocol. 


   .. code-block:: c
      :caption: Definition
   
      struct ymo_proto {
          const char*          name; /* Plain text protocol name */
          void*                data;
          struct ymo_proto_vt  vtable;
      };