1 /* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25 /* 26 * These are used to optionally pass an array of index = C string, binary array, 27 * or ulong tokens to the abstract transport or protocol. For example if it's 28 * raw socket transport, then the DNS address to connect to and the port are 29 * passed using these when the client created and bound to the transport. 30 */ 31 32 typedef struct lws_token_map { 33 union { 34 const char *value; 35 uint8_t *bvalue; 36 unsigned long lvalue; 37 } u; 38 short name_index; /* 0 here indicates end of array */ 39 short length_or_zero; 40 } lws_token_map_t; 41 42 /* 43 * The indvidual protocols and transports define their own name_index-es which 44 * are meaningful to them. Define index 0 globally as the end of an array of 45 * them, and provide bases so user protocol and transport ones don't overlap. 46 */ 47 48 enum { 49 LTMI_END_OF_ARRAY, 50 51 LTMI_PROTOCOL_BASE = 2048, 52 53 LTMI_TRANSPORT_BASE = 4096 54 }; 55 56 struct lws_abs_transport; 57 struct lws_abs_protocol; 58 typedef struct lws_abs lws_abs_t; 59 60 LWS_VISIBLE LWS_EXTERN const lws_token_map_t * 61 lws_abs_get_token(const lws_token_map_t *token_map, short name_index); 62 63 /* 64 * the combination of a protocol, transport, and token maps for each 65 */ 66 67 typedef void lws_abs_transport_inst_t; 68 typedef void lws_abs_protocol_inst_t; 69 70 /** 71 * lws_abstract_alloc() - allocate and configure an lws_abs_t 72 * 73 * \param vhost: the struct lws_vhost to bind to 74 * \param user: opaque user pointer 75 * \param abstract_path: "protocol.transport" names 76 * \param ap_tokens: tokens for protocol options 77 * \param at_tokens: tokens for transport 78 * \param seq: optional sequencer we should bind to, or NULL 79 * \param opaque_user_data: data given in sequencer callback, if any 80 * 81 * Returns an allocated lws_abs_t pointer set up with the other arguments. 82 * 83 * Doesn't create a connection instance, just allocates the lws_abs_t and 84 * sets it up with the arguments. 85 * 86 * Returns NULL is there's any problem. 87 */ 88 LWS_VISIBLE LWS_EXTERN lws_abs_t * 89 lws_abstract_alloc(struct lws_vhost *vhost, void *user, 90 const char *abstract_path, const lws_token_map_t *ap_tokens, 91 const lws_token_map_t *at_tokens, struct lws_sequencer *seq, 92 void *opaque_user_data); 93 94 /** 95 * lws_abstract_free() - free an allocated lws_abs_t 96 * 97 * \param pabs: pointer to the lws_abs_t * to free 98 * 99 * Frees and sets the pointer to NULL. 100 */ 101 102 LWS_VISIBLE LWS_EXTERN void 103 lws_abstract_free(lws_abs_t **pabs); 104 105 /** 106 * lws_abs_bind_and_create_instance - use an abstract protocol and transport 107 * 108 * \param abs: the lws_abs_t describing the combination desired 109 * 110 * This instantiates an abstract protocol and abstract transport bound together. 111 * A single heap allocation is made for the combination and the protocol and 112 * transport creation ops are called on it. The ap_tokens and at_tokens 113 * are consulted by the creation ops to decide the details of the protocol and 114 * transport for the instance. 115 */ 116 LWS_VISIBLE LWS_EXTERN lws_abs_t * 117 lws_abs_bind_and_create_instance(const lws_abs_t *ai); 118 119 /** 120 * lws_abs_destroy_instance() - destroys an instance 121 * 122 * \param ai: pointer to the ai pointer to destroy 123 * 124 * This is for destroying an instance created by 125 * lws_abs_bind_and_create_instance() above. 126 * 127 * Calls the protocol and transport destroy operations on the instance, then 128 * frees the combined allocation in one step. The pointer ai is set to NULL. 129 */ 130 LWS_VISIBLE LWS_EXTERN void 131 lws_abs_destroy_instance(lws_abs_t **ai); 132 133 /* 134 * bring in all the protocols and transports definitions 135 */ 136 137 #include <libwebsockets/abstract/protocols.h> 138 #include <libwebsockets/abstract/transports.h> 139