1/******************************************************************************
2 *
3 *  Copyright (C) 2014 Google, Inc.
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at:
8 *
9 *  http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 *
17 ******************************************************************************/
18
19#pragma once
20
21#include <stdbool.h>
22#include <stddef.h>
23#include <stdint.h>
24#include <sys/types.h>
25
26typedef struct reactor_t reactor_t;
27typedef struct socket_t socket_t;
28typedef uint16_t port_t;
29
30typedef void (*socket_cb)(socket_t *socket, void *context);
31
32// Returns a new socket object. The socket is in an idle, disconnected state when
33// it is returned by this function. The returned object must be freed by calling
34// |socket_free|. Returns NULL on failure.
35socket_t *socket_new(void);
36
37// Returns a new socket object backed by |fd|. The socket object is in whichever
38// state |fd| is in when it was passed to this function. The returned object must
39// be freed by calling |socket_free|. Returns NULL on failure. If this function
40// is successful, ownership of |fd| is transferred and the caller must not close it.
41socket_t *socket_new_from_fd(int fd);
42
43// Frees a socket object created by |socket_new| or |socket_accept|. |socket| may
44// be NULL. If the socket was connected, it will be disconnected.
45void socket_free(socket_t *socket);
46
47// Puts |socket| in listening mode for incoming TCP connections on the specified
48// |port| and the loopback IPv4 address. Returns true on success, false on
49// failure (e.g. |port| is bound by another socket). |socket| may not be NULL.
50bool socket_listen(const socket_t *socket, port_t port);
51
52// Blocks on a listening socket, |socket|, until a client connects to it. Returns
53// a connected socket on success, NULL on failure. The returned object must be
54// freed by calling |socket_free|. |socket| may not be NULL.
55socket_t *socket_accept(const socket_t *socket);
56
57// Reads up to |count| bytes from |socket| into |buf|. This function will not
58// block. This function returns a positive integer representing the number
59// of bytes copied into |buf| on success, 0 if the socket has disconnected,
60// and -1 on error. This function may return a value less than |count| if not
61// enough data is currently available. If this function returns -1, errno will
62// also be set (see recv(2) for possible errno values). However, if the reading
63// system call was interrupted with errno of EINTR, the read operation is
64// restarted internally without propagating EINTR back to the caller. If there
65// were no bytes available to be read, this function returns -1 and sets errno
66// to EWOULDBLOCK. Neither |socket| nor |buf| may be NULL.
67ssize_t socket_read(const socket_t *socket, void *buf, size_t count);
68
69// Writes up to |count| bytes from |buf| into |socket|. This function will not
70// block. Returns a positive integer representing the number of bytes written
71// to |socket| on success, 0 if the socket has disconnected, and -1 on error.
72// This function may return a value less than |count| if writing more bytes
73// would result in blocking. If this function returns -1, errno will also be
74// set (see send(2) for possible errno values). However, if the writing system
75// call was interrupted with errno of EINTR, the write operation is restarted
76// internally without propagating EINTR back to the caller. If no bytes could
77// be written without blocking, this function will return -1 and set errno to
78// EWOULDBLOCK. Neither |socket| nor |buf| may be NULL.
79ssize_t socket_write(const socket_t *socket, const void *buf, size_t count);
80
81// This function performs the same write operation as |socket_write| and also
82// sends the file descriptor |fd| over the socket to a remote process. Ownership
83// of |fd| transfers to this function and the descriptor must not be used any longer.
84// If |fd| is INVALID_FD, this function behaves the same as |socket_write|.
85ssize_t socket_write_and_transfer_fd(const socket_t *socket, const void *buf, size_t count, int fd);
86
87// Returns the number of bytes that can be read from |socket| without blocking. On error,
88// this function returns -1. |socket| may not be NULL.
89//
90// Note: this function should not be part of the socket interface. It is only provided as
91//       a stop-gap until we can refactor away code that depends on a priori knowledge of
92//       the byte count. Do not use this function unless you need it while refactoring
93//       legacy bluedroid code.
94ssize_t socket_bytes_available(const socket_t *socket);
95
96// Registers |socket| with the |reactor|. When the socket becomes readable, |read_cb|
97// will be called. When the socket becomes writeable, |write_cb| will be called. The
98// |context| parameter is passed, untouched, to each of the callback routines. Neither
99// |socket| nor |reactor| may be NULL. |read_cb|, |write_cb|, and |context| may be NULL.
100void socket_register(socket_t *socket, reactor_t *reactor, void *context, socket_cb read_cb, socket_cb write_cb);
101
102// Unregisters |socket| from whichever reactor it is registered with, if any. This
103// function is idempotent.
104void socket_unregister(socket_t *socket);
105