Session
=========




---------------------------------------------------------------
Types:
---------------------------------------------------------------



.. c:type:: ymo_ws_frame_flags_t

   Defines WS message frame flags. 


   .. code-block:: c
      :caption: Definition
   
      typedef union ymo_ws_frame_flags {
          uint8_t  packed;
          struct {
              /* TODO: switch to flag and masks. */
      #if defined(WORDS_BIGENDIAN) && (WORDS_BIGENDIAN == 1)
              uint8_t  fin     : 1;
              uint8_t  rsv1    : 1;
              uint8_t  rsv2    : 1;
              uint8_t  rsv3    : 1;
              uint8_t  op_code : 4;
      #else
              uint8_t  op_code : 4;
              uint8_t  rsv3    : 1;
              uint8_t  rsv2    : 1;
              uint8_t  rsv1    : 1;
              uint8_t  fin     : 1;
      #endif /* BIG_ENDIAN */
          };
      } ymo_ws_frame_flags_t;


.. c:type:: ymo_ws_frame_t

   WebSocket frame 


   .. code-block:: c
      :caption: Definition
   
      typedef struct ymo_ws_frame {
          uint64_t  len;     /* TODO: just use top-bit for the masked flag? */
          size_t    parsed;
      
          /* For incoming messages: */
          uint8_t               masking_key[4] YMO_ATTR_ALIGNED(sizeof(uint32_t));
          ws_parse_state_t      parse_state;
          uint8_t               masked;
          ymo_ws_frame_flags_t  flags;
      
          /* HACK HACK HACK */
          char*   buffer;
          size_t  buf_len;
      
          /* The following have mutually exclusive lifecycles: */
          union {
              uint8_t  mask_mod;
              uint8_t  len_idx;
          };
      
      } ymo_ws_frame_t;


.. c:struct:: ymo_ws_session

   Internal structure used to manage a yimmo ws session. 


   .. code-block:: c
      :caption: Definition
   
      struct ymo_ws_session {
          /* TODO: can we get rid of embedding the conn in the session? */
          ymo_conn_t*          conn;
          ymo_ws_proto_data_t* p_data;     /* HACK */
          ymo_ws_frame_t       frame_in;
          ymo_bucket_t*        recv_head;
          ymo_bucket_t*        recv_tail;
          ymo_bucket_t*        send_head;
          ymo_bucket_t*        send_tail;
      
          ws_session_state_t   state;
          ws_msg_type_t        msg_type;
      
          /* Experimentation: */
          ymo_utf8_state_t  utf8_state;
      
          /* Buffered messages (if buffering is enabled), we buffer the
           * whole message — up to WS_MSG_LEN_MAX bytes — and deliver that):
           */
          char*   msg;
          char*   msg_end;
          size_t  msg_len;
      
          void*   user_data;
      };


.. c:function:: ymo_ws_session_t* ymo_ws_session_create( ymo_ws_proto_data_t* p_data, ymo_conn_t* conn)

   Create a new WS session. 



.. c:function:: ymo_status_t ymo_ws_session_alloc_frame( ymo_ws_session_t* session, size_t len)

   Used internally by WS protocol to allocate space for an incoming
   frame.



.. c:function:: void ymo_ws_session_free(ymo_ws_session_t* session)

   Clear and free the given ws session object, including any nested data
   which has been dynamically allocated. 



.. c:function:: ymo_status_t ymo_ws_session_send_no_check( ymo_ws_session_t* session, uint8_t flags, ymo_bucket_t* payload)

   Send without param/state validation (internal protocol use only):