~ubuntu-branches/ubuntu/vivid/libwebsockets/vivid : revision 2

1

/*

2

* libwebsockets - small server side websockets and web server implementation

3

*

4

5

*

6

* This library is free software; you can redistribute it and/or

7

* modify it under the terms of the GNU Lesser General Public

8

* License as published by the Free Software Foundation:

9

* version 2.1 of the License.

10

*

11

* This library is distributed in the hope that it will be useful,

12

* but WITHOUT ANY WARRANTY; without even the implied warranty of

13

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

14

* Lesser General Public License for more details.

15

*

16

* You should have received a copy of the GNU Lesser General Public

17

* License along with this library; if not, write to the Free Software

18

* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

19

* MA 02110-1301 USA

20

*/

21

22

#ifndef __LIBWEBSOCKET_H__

23

#define __LIBWEBSOCKET_H__

24

25

#ifdef __cplusplus

26

extern "C" {

27

#include <cstddef>

28

#endif

29

30

#ifdef WIN32

31

32

#ifndef WIN32_LEAN_AND_MEAN

33

#define WIN32_LEAN_AND_MEAN

34

#endif

35

#include <winsock2.h>

36

#include <ws2tcpip.h>

37

#include <stddef.h>

38

#include "../win32port/win32helpers/websock-w32.h"

39

40

#include "../win32port/win32helpers/gettimeofday.h"

41

42

#define strcasecmp stricmp

43

#define getdtablesize() 30000

44

45

typedef int ssize_t;

46

47

#ifdef LWS_DLL

48

#ifdef LWS_INTERNAL

49

#define LWS_EXTERN extern __declspec(dllexport)

50

#else

51

#define LWS_EXTERN extern __declspec(dllimport)

52

#endif

53

#endif

54

55

#else // NOT WIN32

56

#include <poll.h>

57

#include <unistd.h>

58

#endif

59

60

#include <assert.h>

61

62

#ifndef LWS_EXTERN

63

#define LWS_EXTERN extern

64

#endif

65

66

#define CONTEXT_PORT_NO_LISTEN 0

67

#define MAX_MUX_RECURSION 2

68

69

enum lws_log_levels {

70

LLL_ERR = 1 << 0,

71

LLL_WARN = 1 << 1,

72

LLL_NOTICE = 1 << 2,

73

LLL_INFO = 1 << 3,

74

LLL_DEBUG = 1 << 4,

75

LLL_PARSER = 1 << 5,

76

LLL_HEADER = 1 << 6,

77

LLL_EXT = 1 << 7,

78

LLL_CLIENT = 1 << 8,

79

LLL_LATENCY = 1 << 9,

80

81

LLL_COUNT = 10 /* set to count of valid flags */

82

};

83

84

LWS_EXTERN void _lws_log(int filter, const char *format, ...);

85

86

/* notice, warn and log are always compiled in */

87

#define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)

88

#define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)

89

#define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)

90

/*

91

* weaker logging can be deselected at configure time using --disable-debug

92

* that gets rid of the overhead of checking while keeping _warn and _err

93

* active

94

*/

95

#ifdef _DEBUG

96

97

#define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)

98

#define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)

99

#define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)

100

#define lwsl_header(...) _lws_log(LLL_HEADER, __VA_ARGS__)

101

#define lwsl_ext(...) _lws_log(LLL_EXT, __VA_ARGS__)

102

#define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)

103

#define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)

104

LWS_EXTERN void lwsl_hexdump(void *buf, size_t len);

105

106

#else /* no debug */

107

108

#define lwsl_info(...)

109

#define lwsl_debug(...)

110

#define lwsl_parser(...)

111

#define lwsl_header(...)

112

#define lwsl_ext(...)

113

#define lwsl_client(...)

114

#define lwsl_latency(...)

115

#define lwsl_hexdump(a, b)

116

117

#endif

118

119

enum libwebsocket_context_options {

120

LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,

121

LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = 4,

122

};

123

124

enum libwebsocket_callback_reasons {

125

LWS_CALLBACK_ESTABLISHED,

126

LWS_CALLBACK_CLIENT_CONNECTION_ERROR,

127

LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH,

128

LWS_CALLBACK_CLIENT_ESTABLISHED,

129

LWS_CALLBACK_CLOSED,

130

LWS_CALLBACK_RECEIVE,

131

LWS_CALLBACK_CLIENT_RECEIVE,

132

LWS_CALLBACK_CLIENT_RECEIVE_PONG,

133

LWS_CALLBACK_CLIENT_WRITEABLE,

134

LWS_CALLBACK_SERVER_WRITEABLE,

135

LWS_CALLBACK_HTTP,

136

LWS_CALLBACK_HTTP_FILE_COMPLETION,

137

LWS_CALLBACK_FILTER_NETWORK_CONNECTION,

138

LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,

139

LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,

140

LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,

141

LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,

142

LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER,

143

LWS_CALLBACK_CONFIRM_EXTENSION_OKAY,

144

LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED,

145

LWS_CALLBACK_PROTOCOL_INIT,

146

LWS_CALLBACK_PROTOCOL_DESTROY,

147

/* external poll() management support */

148

LWS_CALLBACK_ADD_POLL_FD,

149

LWS_CALLBACK_DEL_POLL_FD,

150

LWS_CALLBACK_SET_MODE_POLL_FD,

151

LWS_CALLBACK_CLEAR_MODE_POLL_FD,

152

};

153

154

#ifndef LWS_NO_EXTENSIONS

155

enum libwebsocket_extension_callback_reasons {

156

LWS_EXT_CALLBACK_SERVER_CONTEXT_CONSTRUCT,

157

LWS_EXT_CALLBACK_CLIENT_CONTEXT_CONSTRUCT,

158

LWS_EXT_CALLBACK_SERVER_CONTEXT_DESTRUCT,

159

LWS_EXT_CALLBACK_CLIENT_CONTEXT_DESTRUCT,

160

LWS_EXT_CALLBACK_CONSTRUCT,

161

LWS_EXT_CALLBACK_CLIENT_CONSTRUCT,

162

LWS_EXT_CALLBACK_CHECK_OK_TO_REALLY_CLOSE,

163

LWS_EXT_CALLBACK_CHECK_OK_TO_PROPOSE_EXTENSION,

164

LWS_EXT_CALLBACK_DESTROY,

165

LWS_EXT_CALLBACK_DESTROY_ANY_WSI_CLOSING,

166

LWS_EXT_CALLBACK_ANY_WSI_ESTABLISHED,

167

LWS_EXT_CALLBACK_PACKET_RX_PREPARSE,

168

LWS_EXT_CALLBACK_PACKET_TX_PRESEND,

169

LWS_EXT_CALLBACK_PACKET_TX_DO_SEND,

170

LWS_EXT_CALLBACK_HANDSHAKE_REPLY_TX,

171

LWS_EXT_CALLBACK_FLUSH_PENDING_TX,

172

LWS_EXT_CALLBACK_EXTENDED_PAYLOAD_RX,

173

LWS_EXT_CALLBACK_CAN_PROXY_CLIENT_CONNECTION,

174

LWS_EXT_CALLBACK_1HZ,

175

LWS_EXT_CALLBACK_REQUEST_ON_WRITEABLE,

176

LWS_EXT_CALLBACK_IS_WRITEABLE,

177

LWS_EXT_CALLBACK_PAYLOAD_TX,

178

LWS_EXT_CALLBACK_PAYLOAD_RX,

179

};

180

#endif

181

182

enum libwebsocket_write_protocol {

183

LWS_WRITE_TEXT,

184

LWS_WRITE_BINARY,

185

LWS_WRITE_CONTINUATION,

186

LWS_WRITE_HTTP,

187

188

/* special 04+ opcodes */

189

190

LWS_WRITE_CLOSE,

191

LWS_WRITE_PING,

192

LWS_WRITE_PONG,

193

194

/* flags */

195

196

LWS_WRITE_NO_FIN = 0x40,

197

/*

198

* client packet payload goes out on wire unmunged

199

* only useful for security tests since normal servers cannot

200

* decode the content if used

201

*/

202

LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80

203

};

204

205

/*

206

* you need these to look at headers that have been parsed if using the

207

* LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum

208

* list below is absent, .token = NULL and token_len = 0. Otherwise .token

209

* points to .token_len chars containing that header content.

210

*/

211

212

struct lws_tokens {

213

char *token;

214

int token_len;

215

};

216

217

enum lws_token_indexes {

218

WSI_TOKEN_GET_URI,

219

WSI_TOKEN_HOST,

220

WSI_TOKEN_CONNECTION,

221

WSI_TOKEN_KEY1,

222

WSI_TOKEN_KEY2,

223

WSI_TOKEN_PROTOCOL,

224

WSI_TOKEN_UPGRADE,

225

WSI_TOKEN_ORIGIN,

226

WSI_TOKEN_DRAFT,

227

WSI_TOKEN_CHALLENGE,

228

229

/* new for 04 */

230

WSI_TOKEN_KEY,

231

WSI_TOKEN_VERSION,

232

WSI_TOKEN_SWORIGIN,

233

234

/* new for 05 */

235

WSI_TOKEN_EXTENSIONS,

236

237

/* client receives these */

238

WSI_TOKEN_ACCEPT,

239

WSI_TOKEN_NONCE,

240

WSI_TOKEN_HTTP,

241

WSI_TOKEN_MUXURL,

242

243

/* use token storage to stash these */

244

245

_WSI_TOKEN_CLIENT_SENT_PROTOCOLS,

246

_WSI_TOKEN_CLIENT_PEER_ADDRESS,

247

_WSI_TOKEN_CLIENT_URI,

248

_WSI_TOKEN_CLIENT_HOST,

249

_WSI_TOKEN_CLIENT_ORIGIN,

250

251

/* always last real token index*/

252

WSI_TOKEN_COUNT,

253

/* parser state additions */

254

WSI_TOKEN_NAME_PART,

255

WSI_TOKEN_SKIPPING,

256

WSI_TOKEN_SKIPPING_SAW_CR,

257

WSI_PARSING_COMPLETE,

258

WSI_INIT_TOKEN_MUXURL,

259

};

260

261

/*

262

* From RFC 6455

263

1000

264

265

1000 indicates a normal closure, meaning that the purpose for

266

which the connection was established has been fulfilled.

267

268

1001

269

270

1001 indicates that an endpoint is "going away", such as a server

271

going down or a browser having navigated away from a page.

272

273

1002

274

275

1002 indicates that an endpoint is terminating the connection due

276

to a protocol error.

277

278

1003

279

280

1003 indicates that an endpoint is terminating the connection

281

because it has received a type of data it cannot accept (e.g., an

282

endpoint that understands only text data MAY send this if it

283

receives a binary message).

284

285

1004

286

287

Reserved. The specific meaning might be defined in the future.

288

289

1005

290

291

1005 is a reserved value and MUST NOT be set as a status code in a

292

Close control frame by an endpoint. It is designated for use in

293

applications expecting a status code to indicate that no status

294

code was actually present.

295

296

1006

297

298

1006 is a reserved value and MUST NOT be set as a status code in a

299

Close control frame by an endpoint. It is designated for use in

300

applications expecting a status code to indicate that the

301

connection was closed abnormally, e.g., without sending or

302

receiving a Close control frame.

303

304

1007

305

306

1007 indicates that an endpoint is terminating the connection

307

because it has received data within a message that was not

308

consistent with the type of the message (e.g., non-UTF-8 [RFC3629]

309

data within a text message).

310

311

1008

312

313

1008 indicates that an endpoint is terminating the connection

314

because it has received a message that violates its policy. This

315

is a generic status code that can be returned when there is no

316

other more suitable status code (e.g., 1003 or 1009) or if there

317

is a need to hide specific details about the policy.

318

319

1009

320

321

1009 indicates that an endpoint is terminating the connection

322

because it has received a message that is too big for it to

323

process.

324

325

1010

326

327

1010 indicates that an endpoint (client) is terminating the

328

connection because it has expected the server to negotiate one or

329

more extension, but the server didn't return them in the response

330

message of the WebSocket handshake. The list of extensions that

331

are needed SHOULD appear in the /reason/ part of the Close frame.

332

Note that this status code is not used by the server, because it

333

can fail the WebSocket handshake instead.

334

335

1011

336

337

1011 indicates that a server is terminating the connection because

338

it encountered an unexpected condition that prevented it from

339

fulfilling the request.

340

341

1015

342

343

1015 is a reserved value and MUST NOT be set as a status code in a

344

Close control frame by an endpoint. It is designated for use in

345

applications expecting a status code to indicate that the

346

connection was closed due to a failure to perform a TLS handshake

347

(e.g., the server certificate can't be verified).

348

*/

349

350

enum lws_close_status {

351

LWS_CLOSE_STATUS_NOSTATUS = 0,

352

LWS_CLOSE_STATUS_NORMAL = 1000,

353

LWS_CLOSE_STATUS_GOINGAWAY = 1001,

354

LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,

355

LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,

356

LWS_CLOSE_STATUS_RESERVED = 1004,

357

LWS_CLOSE_STATUS_NO_STATUS = 1005,

358

LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,

359

LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,

360

LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,

361

LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,

362

LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,

363

LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,

364

LWS_CLOSE_STATUS_TLS_FAILURE = 1015,

365

};

366

367

struct libwebsocket;

368

struct libwebsocket_context;

369

/* needed even with extensions disabled for create context */

370

struct libwebsocket_extension;

371

372

/**

373

* callback_function() - User server actions

374

* @context: Websockets context

375

* @wsi: Opaque websocket instance pointer

376

* @reason: The reason for the call

377

* @user: Pointer to per-session user data allocated by library

378

* @in: Pointer used for some callback reasons

379

* @len: Length set for some callback reasons

380

*

381

* This callback is the way the user controls what is served. All the

382

* protocol detail is hidden and handled by the library.

383

*

384

* For each connection / session there is user data allocated that is

385

* pointed to by "user". You set the size of this user data area when

386

* the library is initialized with libwebsocket_create_server.

387

*

388

* You get an opportunity to initialize user data when called back with

389

* LWS_CALLBACK_ESTABLISHED reason.

390

*

391

* LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with

392

* an incoming client

393

*

394

* LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has

395

* been unable to complete a handshake with the remote server

396

*

397

* LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH: this is the last chance for the

398

* client user code to examine the http headers

399

* and decide to reject the connection. If the

400

* content in the headers is interesting to the

401

* client (url, etc) it needs to copy it out at

402

* this point since it will be destroyed before

403

* the CLIENT_ESTABLISHED call

404

*

405

* LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed

406

* a handshake with the remote server

407

*

408

* LWS_CALLBACK_CLOSED: when the websocket session ends

409

*

410

* LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a

411

* remote client, it can be found at *in and is

412

* len bytes long

413

*

414

* LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,

415

* they appear with this callback reason. PONG

416

* packets only exist in 04+ protocol

417

*

418

* LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the

419

* client connection, it can be found at *in and

420

* is len bytes long

421

*

422

* LWS_CALLBACK_HTTP: an http request has come from a client that is not

423

* asking to upgrade the connection to a websocket

424

* one. This is a chance to serve http content,

425

* for example, to send a script to the client

426

* which will then open the websockets connection.

427

* @in points to the URI path requested and

428

* libwebsockets_serve_http_file() makes it very

429

* simple to send back a file to the client.

430

* Normally after sending the file you are done

431

* with the http connection, since the rest of the

432

* activity will come by websockets from the script

433

* that was delivered by http, so you will want to

434

* return 1; to close and free up the connection.

435

* That's important because it uses a slot in the

436

* total number of client connections allowed set

437

* by MAX_CLIENTS.

438

*

439

* LWS_CALLBACK_HTTP_FILE_COMPLETION: a file requested to be send down

440

* http link has completed.

441

*

442

* LWS_CALLBACK_CLIENT_WRITEABLE:

443

* LWS_CALLBACK_SERVER_WRITEABLE: If you call

444

* libwebsocket_callback_on_writable() on a connection, you will

445

* get one of these callbacks coming when the connection socket

446

* is able to accept another write packet without blocking.

447

* If it already was able to take another packet without blocking,

448

* you'll get this callback at the next call to the service loop

449

* function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE

450

* and servers get LWS_CALLBACK_SERVER_WRITEABLE.

451

*

452

* LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to

453

* the server at network level; the connection is accepted but then

454

* passed to this callback to decide whether to hang up immediately

455

* or not, based on the client IP. @user contains the connection

456

* socket's descriptor. Return non-zero to terminate

457

* the connection before sending or receiving anything.

458

* Because this happens immediately after the network connection

459

* from the client, there's no websocket protocol selected yet so

460

* this callback is issued only to protocol 0.

461

*

462

* LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has

463

* been received and parsed from the client, but the response is

464

* not sent yet. Return non-zero to disallow the connection.

465

* @user is a pointer to an array of struct lws_tokens, you can

466

* use the header enums lws_token_indexes from libwebsockets.h

467

* to check for and read the supported header presence and

468

* content before deciding to allow the handshake to proceed or

469

* to kill the connection.

470

*

471

* LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for

472

* including OpenSSL support, this callback allows your user code

473

* to perform extra SSL_CTX_load_verify_locations() or similar

474

* calls to direct OpenSSL where to find certificates the client

475

* can use to confirm the remote server identity. @user is the

476

* OpenSSL SSL_CTX*

477

*

478

* LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for

479

* including OpenSSL support, this callback allows your user code

480

* to load extra certifcates into the server which allow it to

481

* verify the validity of certificates returned by clients. @user

482

* is the server's OpenSSL SSL_CTX*

483

*

484

* LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the

485

* libwebsockets context was created with the option

486

* LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this

487

* callback is generated during OpenSSL verification of the cert

488

* sent from the client. It is sent to protocol[0] callback as

489

* no protocol has been negotiated on the connection yet.

490

* Notice that the libwebsockets context and wsi are both NULL

491

* during this callback. See

492

* http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html

493

* to understand more detail about the OpenSSL callback that

494

* generates this libwebsockets callback and the meanings of the

495

* arguments passed. In this callback, @user is the x509_ctx,

496

* @in is the ssl pointer and @len is preverify_ok

497

* Notice that this callback maintains libwebsocket return

498

* conventions, return 0 to mean the cert is OK or 1 to fail it.

499

* This also means that if you don't handle this callback then

500

* the default callback action of returning 0 allows the client

501

* certificates.

502

*

503

* LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens

504

* when a client handshake is being compiled. @user is NULL,

505

* @in is a char **, it's pointing to a char * which holds the

506

* next location in the header buffer where you can add

507

* headers, and @len is the remaining space in the header buffer,

508

* which is typically some hundreds of bytes. So, to add a canned

509

* cookie, your handler code might look similar to:

510

*

511

* char **p = (char **)in;

512

*

513

* if (len < 100)

514

* return 1;

515

*

516

* *p += sprintf(*p, "Cookie: a=b\x0d\x0a");

517

*

518

* return 0;

519

*

520

* Notice if you add anything, you just have to take care about

521

* the CRLF on the line you added. Obviously this callback is

522

* optional, if you don't handle it everything is fine.

523

*

524

* Notice the callback is coming to protocols[0] all the time,

525

* because there is no specific protocol handshook yet.

526

*

527

* LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code

528

* sees that it does support a requested extension, before

529

* accepting the extension by additing to the list sent back to

530

* the client it gives this callback just to check that it's okay

531

* to use that extension. It calls back to the requested protocol

532

* and with @in being the extension name, @len is 0 and @user is

533

* valid. Note though at this time the ESTABLISHED callback hasn't

534

* happened yet so if you initialize @user content there, @user

535

* content during this callback might not be useful for anything.

536

* Notice this callback comes to protocols[0].

537

*

538

* LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED: When a client

539

* connection is being prepared to start a handshake to a server,

540

* each supported extension is checked with protocols[0] callback

541

* with this reason, giving the user code a chance to suppress the

542

* claim to support that extension by returning non-zero. If

543

* unhandled, by default 0 will be returned and the extension

544

* support included in the header to the server. Notice this

545

* callback comes to protocols[0].

546

*

547

* LWS_CALLBACK_PROTOCOL_INIT: One-time call per protocol so it can

548

* do initial setup / allocations etc

549

*

550

* LWS_CALLBACK_PROTOCOL_DESTROY: One-time call per protocol indicating

551

* this protocol won't get used at all after this callback, the

552

* context is getting destroyed. Take the opportunity to

553

* deallocate everything that was allocated by the protocol.

554

*

555

* The next four reasons are optional and only need taking care of if you

556

* will be integrating libwebsockets sockets into an external polling

557

* array.

558

*

559

* LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop

560

* internally, but in the case you are integrating with another

561

* server you will need to have libwebsocket sockets share a

562

* polling array with the other server. This and the other

563

* POLL_FD related callbacks let you put your specialized

564

* poll array interface code in the callback for protocol 0, the

565

* first protocol you support, usually the HTTP protocol in the

566

* serving case. This callback happens when a socket needs to be

567

* added to the polling loop: @user contains the fd, and

568

* @len is the events bitmap (like, POLLIN). If you are using the

569

* internal polling loop (the "service" callback), you can just

570

* ignore these callbacks.

571

*

572

* LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor

573

* needs to be removed from an external polling array. @user is

574

* the socket desricptor. If you are using the internal polling

575

* loop, you can just ignore it.

576

*

577

* LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets

578

* wants to modify the events for the socket descriptor in @user.

579

* The handler should OR @len on to the events member of the pollfd

580

* struct for this socket descriptor. If you are using the

581

* internal polling loop, you can just ignore it.

582

*

583

* LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets

584

* wants to modify the events for the socket descriptor in @user.

585

* The handler should AND ~@len on to the events member of the

586

* pollfd struct for this socket descriptor. If you are using the

587

* internal polling loop, you can just ignore it.

588

*/

589

LWS_EXTERN int callback(struct libwebsocket_context *context,

590

struct libwebsocket *wsi,

591

enum libwebsocket_callback_reasons reason, void *user,

592

void *in, size_t len);

593

594

typedef int (callback_function)(struct libwebsocket_context *context,

595

struct libwebsocket *wsi,

596

enum libwebsocket_callback_reasons reason, void *user,

597

void *in, size_t len);

598

599

#ifndef LWS_NO_EXTENSIONS

600

/**

601

* extension_callback_function() - Hooks to allow extensions to operate

602

* @context: Websockets context

603

* @ext: This extension

604

* @wsi: Opaque websocket instance pointer

605

* @reason: The reason for the call

606

* @user: Pointer to per-session user data allocated by library

607

* @in: Pointer used for some callback reasons

608

* @len: Length set for some callback reasons

609

*

610

* Each extension that is active on a particular connection receives

611

* callbacks during the connection lifetime to allow the extension to

612

* operate on websocket data and manage itself.

613

*

614

* Libwebsockets takes care of allocating and freeing "user" memory for

615

* each active extension on each connection. That is what is pointed to

616

* by the @user parameter.

617

*

618

* LWS_EXT_CALLBACK_CONSTRUCT: called when the server has decided to

619

* select this extension from the list provided by the client,

620

* just before the server will send back the handshake accepting

621

* the connection with this extension active. This gives the

622

* extension a chance to initialize its connection context found

623

* in @user.

624

*

625

* LWS_EXT_CALLBACK_CLIENT_CONSTRUCT: same as LWS_EXT_CALLBACK_CONSTRUCT

626

* but called when client is instantiating this extension. Some

627

* extensions will work the same on client and server side and then

628

* you can just merge handlers for both CONSTRUCTS.

629

*

630

* LWS_EXT_CALLBACK_DESTROY: called when the connection the extension was

631

* being used on is about to be closed and deallocated. It's the

632

* last chance for the extension to deallocate anything it has

633

* allocated in the user data (pointed to by @user) before the

634

* user data is deleted. This same callback is used whether you

635

* are in client or server instantiation context.

636

*

637

* LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on

638

* a connection, and a packet of data arrived at the connection,

639

* it is passed to this callback to give the extension a chance to

640

* change the data, eg, decompress it. @user is pointing to the

641

* extension's private connection context data, @in is pointing

642

* to an lws_tokens struct, it consists of a char * pointer called

643

* token, and an int called token_len. At entry, these are

644

* set to point to the received buffer and set to the content

645

* length. If the extension will grow the content, it should use

646

* a new buffer allocated in its private user context data and

647

* set the pointed-to lws_tokens members to point to its buffer.

648

*

649

* LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as

650

* LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the

651

* extension a chance to change websocket data just before it will

652

* be sent out. Using the same lws_token pointer scheme in @in,

653

* the extension can change the buffer and the length to be

654

* transmitted how it likes. Again if it wants to grow the

655

* buffer safely, it should copy the data into its own buffer and

656

* set the lws_tokens token pointer to it.

657

*/

658

LWS_EXTERN int extension_callback(struct libwebsocket_context *context,

659

struct libwebsocket_extension *ext,

660

struct libwebsocket *wsi,

661

enum libwebsocket_extension_callback_reasons reason,

662

void *user, void *in, size_t len);

663

664

typedef int (extension_callback_function)(struct libwebsocket_context *context,

665

struct libwebsocket_extension *ext,

666

struct libwebsocket *wsi,

667

enum libwebsocket_extension_callback_reasons reason,

668

void *user, void *in, size_t len);

669

#endif

670

671

/**

672

* struct libwebsocket_protocols - List of protocols and handlers server

673

* supports.

674

* @name: Protocol name that must match the one given in the client

675

* Javascript new WebSocket(url, 'protocol') name

676

* @callback: The service callback used for this protocol. It allows the

677

* service action for an entire protocol to be encapsulated in

678

* the protocol-specific callback

679

* @per_session_data_size: Each new connection using this protocol gets

680

* this much memory allocated on connection establishment and

681

* freed on connection takedown. A pointer to this per-connection

682

* allocation is passed into the callback in the 'user' parameter

683

* @rx_buffer_size: if you want atomic frames delivered to the callback, you

684

* should set this to the size of the biggest legal frame that

685

* you support. If the frame size is exceeded, there is no

686

* error, but the buffer will spill to the user callback when

687

* full, which you can detect by using

688

* libwebsockets_remaining_packet_payload(). Notice that you

689

* just talk about frame size here, the LWS_SEND_BUFFER_PRE_PADDING

690

* and post-padding are automatically also allocated on top.

691

* @owning_server: the server init call fills in this opaque pointer when

692

* registering this protocol with the server.

693

* @protocol_index: which protocol we are starting from zero

694

*

695

* This structure represents one protocol supported by the server. An

696

* array of these structures is passed to libwebsocket_create_server()

697

* allows as many protocols as you like to be handled by one server.

698

*/

699

700

struct libwebsocket_protocols {

701

const char *name;

702

callback_function *callback;

703

size_t per_session_data_size;

704

size_t rx_buffer_size;

705

706

/*

707

* below are filled in on server init and can be left uninitialized,

708

* no need for user to use them directly either

709

*/

710

711

struct libwebsocket_context *owning_server;

712

int protocol_index;

713

};

714

715

#ifndef LWS_NO_EXTENSIONS

716

/**

717

* struct libwebsocket_extension - An extension we know how to cope with

718

*

719

* @name: Formal extension name, eg, "deflate-stream"

720

* @callback: Service callback

721

* @per_session_data_size: Libwebsockets will auto-malloc this much

722

* memory for the use of the extension, a pointer

723

* to it comes in the @user callback parameter

724

* @per_context_private_data: Optional storage for this extension that

725

* is per-context, so it can track stuff across

726

* all sessions, etc, if it wants

727

*/

728

729

struct libwebsocket_extension {

730

const char *name;

731

extension_callback_function *callback;

732

size_t per_session_data_size;

733

void *per_context_private_data;

734

};

735

#endif

736

737

/**

738

* struct lws_context_creation_info: parameters to create context with

739

*

740

* @port: Port to listen on... you can use 0 to suppress listening on

741

* any port, that's what you want if you are not running a

742

* websocket server at all but just using it as a client

743

* @iface: NULL to bind the listen socket to all interfaces, or the

744

* interface name, eg, "eth2"

745

* @protocols: Array of structures listing supported protocols and a protocol-

746

* specific callback for each one. The list is ended with an

747

* entry that has a NULL callback pointer.

748

* It's not const because we write the owning_server member

749

* @extensions: NULL or array of libwebsocket_extension structs listing the

750

* extensions this context supports. If you configured with

751

* --without-extensions, you should give NULL here.

752

* @ssl_cert_filepath: If libwebsockets was compiled to use ssl, and you want

753

* to listen using SSL, set to the filepath to fetch the

754

* server cert from, otherwise NULL for unencrypted

755

* @ssl_private_key_filepath: filepath to private key if wanting SSL mode,

756

* else ignored

757

* @ssl_ca_filepath: CA certificate filepath or NULL

758

* @gid: group id to change to after setting listen socket, or -1.

759

* @uid: user id to change to after setting listen socket, or -1.

760

* @options: 0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK

761

* @user: optional user pointer that can be recovered via the context

762

* pointer using libwebsocket_context_user

763

* @ka_time: 0 for no keepalive, otherwise apply this keepalive timeout to

764

* all libwebsocket sockets, client or server

765

* @ka_probes: if ka_time was nonzero, after the timeout expires how many

766

* times to try to get a response from the peer before giving up

767

* and killing the connection

768

* @ka_interval: if ka_time was nonzero, how long to wait before each ka_probes

769

* attempt

770

*/

771

772

struct lws_context_creation_info {

773

int port;

774

const char *iface;

775

struct libwebsocket_protocols *protocols;

776

struct libwebsocket_extension *extensions;

777

const char *ssl_cert_filepath;

778

const char *ssl_private_key_filepath;

779

const char *ssl_ca_filepath;

780

int gid;

781

int uid;

782

unsigned int options;

783

void *user;

784

int ka_time;

785

int ka_probes;

786

int ka_interval;

787

788

};

789

790

LWS_EXTERN

791

void lws_set_log_level(int level,

792

void (*log_emit_function)(int level, const char *line));

793

794

LWS_EXTERN void

795

lwsl_emit_syslog(int level, const char *line);

796

797

LWS_EXTERN struct libwebsocket_context *

798

libwebsocket_create_context(struct lws_context_creation_info *info);

799

800

LWS_EXTERN void

801

libwebsocket_context_destroy(struct libwebsocket_context *context);

802

803

LWS_EXTERN int

804

libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);

805

806

LWS_EXTERN int

807

libwebsocket_service_fd(struct libwebsocket_context *context,

808

struct pollfd *pollfd);

809

810

LWS_EXTERN void *

811

libwebsocket_context_user(struct libwebsocket_context *context);

812

813

/*

814

* IMPORTANT NOTICE!

815

*

816

* When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)

817

* the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE

818

* buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).

819

*

820

* This allows us to add protocol info before and after the data, and send as

821

* one packet on the network without payload copying, for maximum efficiency.

822

*

823

* So for example you need this kind of code to use libwebsocket_write with a

824

* 128-byte payload

825

*

826

* char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];

827

*

828

* // fill your part of the buffer... for example here it's all zeros

829

* memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);

830

*

831

* libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);

832

*

833

* When sending LWS_WRITE_HTTP, there is no protocol addition and you can just

834

* use the whole buffer without taking care of the above.

835

*/

836

837

/*

838

* this is the frame nonce plus two header plus 8 length

839

* there's an additional two for mux extension per mux nesting level

840

* 2 byte prepend on close will already fit because control frames cannot use

841

* the big length style

842

*/

843

844

#define LWS_SEND_BUFFER_PRE_PADDING (4 + 10 + (2 * MAX_MUX_RECURSION))

845

#define LWS_SEND_BUFFER_POST_PADDING 4

846

847

LWS_EXTERN int

848

libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,

849

enum libwebsocket_write_protocol protocol);

850

851

LWS_EXTERN int

852

libwebsockets_serve_http_file(struct libwebsocket_context *context,

853

struct libwebsocket *wsi, const char *file,

854

const char *content_type);

855

LWS_EXTERN int

856

libwebsockets_serve_http_file_fragment(struct libwebsocket_context *context,

857

struct libwebsocket *wsi);

858

859

LWS_EXTERN const struct libwebsocket_protocols *

860

libwebsockets_get_protocol(struct libwebsocket *wsi);

861

862

LWS_EXTERN int

863

libwebsocket_callback_on_writable(struct libwebsocket_context *context,

864

struct libwebsocket *wsi);

865

866

LWS_EXTERN int

867

libwebsocket_callback_on_writable_all_protocol(

868

const struct libwebsocket_protocols *protocol);

869

870

LWS_EXTERN int

871

libwebsocket_get_socket_fd(struct libwebsocket *wsi);

872

873

LWS_EXTERN int

874

libwebsocket_is_final_fragment(struct libwebsocket *wsi);

875

876

LWS_EXTERN unsigned char

877

libwebsocket_get_reserved_bits(struct libwebsocket *wsi);

878

879

LWS_EXTERN void *

880

libwebsocket_ensure_user_space(struct libwebsocket *wsi);

881

882

LWS_EXTERN int

883

libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);

884

885

LWS_EXTERN size_t

886

libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);

887

888

LWS_EXTERN struct libwebsocket *

889

libwebsocket_client_connect(struct libwebsocket_context *clients,

890

const char *address,

891

int port,

892

int ssl_connection,

893

const char *path,

894

const char *host,

895

const char *origin,

896

const char *protocol,

897

int ietf_version_or_minus_one);

898

899

LWS_EXTERN struct libwebsocket *

900

libwebsocket_client_connect_extended(struct libwebsocket_context *clients,

901

const char *address,

902

int port,

903

int ssl_connection,

904

const char *path,

905

const char *host,

906

const char *origin,

907

const char *protocol,

908

int ietf_version_or_minus_one,

909

void *userdata);

910

911

LWS_EXTERN const char *

912

libwebsocket_canonical_hostname(struct libwebsocket_context *context);

913

914

915

LWS_EXTERN void

916

libwebsockets_get_peer_addresses(struct libwebsocket_context *context,

917

struct libwebsocket *wsi, int fd, char *name, int name_len,

918

char *rip, int rip_len);

919

920

LWS_EXTERN int

921

libwebsockets_get_random(struct libwebsocket_context *context,

922

void *buf, int len);

923

924

LWS_EXTERN int

925

lws_daemonize(const char *_lock_path);

926

927

LWS_EXTERN int

928

lws_send_pipe_choked(struct libwebsocket *wsi);

929

930

LWS_EXTERN int

931

lws_frame_is_binary(struct libwebsocket *wsi);

932

933

LWS_EXTERN unsigned char *

934

libwebsockets_SHA1(const unsigned char *d, size_t n, unsigned char *md);

935

936

LWS_EXTERN int

937

lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);

938

939

LWS_EXTERN int

940

lws_b64_decode_string(const char *in, char *out, int out_size);

941

942

LWS_EXTERN const char *

943

lws_get_library_version(void);

944

945

/* access to headers... only valid while headers valid */

946

947

LWS_EXTERN int

948

lws_hdr_total_length(struct libwebsocket *wsi, enum lws_token_indexes h);

949

950

LWS_EXTERN int

951

lws_hdr_copy(struct libwebsocket *wsi, char *dest, int len,

952

enum lws_token_indexes h);

953

954

/*

955

* Note: this is not normally needed as a user api. It's provided in case it is

956

* useful when integrating with other app poll loop service code.

957

*/

958

959

LWS_EXTERN int

960

libwebsocket_read(struct libwebsocket_context *context,

961

struct libwebsocket *wsi,

962

unsigned char *buf, size_t len);

963

964

#ifndef LWS_NO_EXTENSIONS

965

LWS_EXTERN struct libwebsocket_extension *libwebsocket_get_internal_extensions();

966

#endif

967

968

#ifdef __cplusplus

969

}

970

#endif

971

972

#endif