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
32typedef 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
48enum {
49 LTMI_END_OF_ARRAY,
50
51 LTMI_PROTOCOL_BASE = 2048,
52
53 LTMI_TRANSPORT_BASE = 4096
54};
55
56struct lws_abs_transport;
57struct lws_abs_protocol;
58typedef struct lws_abs lws_abs_t;
59
60LWS_VISIBLE LWS_EXTERN const lws_token_map_t *
61lws_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
67typedef void lws_abs_transport_inst_t;
68typedef 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 */
88LWS_VISIBLE LWS_EXTERN lws_abs_t *
89lws_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
102LWS_VISIBLE LWS_EXTERN void
103lws_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 */
116LWS_VISIBLE LWS_EXTERN lws_abs_t *
117lws_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 */
130LWS_VISIBLE LWS_EXTERN void
131lws_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