1 /****************************************************************************** 2 * 3 * Copyright 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 26 typedef struct reactor_t reactor_t; 27 typedef struct socket_t socket_t; 28 typedef uint16_t port_t; 29 30 typedef void (*socket_cb)(socket_t* socket, void* context); 31 32 // Returns a new socket object. The socket is in an idle, disconnected state 33 // when it is returned by this function. The returned object must be freed by 34 // calling |socket_free|. Returns NULL on failure. 35 socket_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 39 // must be freed by calling |socket_free|. Returns NULL on failure. If this 40 // function is successful, ownership of |fd| is transferred and the caller must 41 // not close it. 42 socket_t* socket_new_from_fd(int fd); 43 44 // Frees a socket object created by |socket_new| or |socket_accept|. |socket| 45 // may be NULL. If the socket was connected, it will be disconnected. 46 void socket_free(socket_t* socket); 47 48 // Puts |socket| in listening mode for incoming TCP connections on the specified 49 // |port| and the loopback IPv4 address. Returns true on success, false on 50 // failure (e.g. |port| is bound by another socket). |socket| may not be NULL. 51 bool socket_listen(const socket_t* socket, port_t port); 52 53 // Blocks on a listening socket, |socket|, until a client connects to it. 54 // Returns a connected socket on success, NULL on failure. The returned object 55 // must be freed by calling |socket_free|. |socket| may not be NULL. 56 socket_t* socket_accept(const socket_t* socket); 57 58 // Reads up to |count| bytes from |socket| into |buf|. This function will not 59 // block. This function returns a positive integer representing the number 60 // of bytes copied into |buf| on success, 0 if the socket has disconnected, 61 // and -1 on error. This function may return a value less than |count| if not 62 // enough data is currently available. If this function returns -1, errno will 63 // also be set (see recv(2) for possible errno values). However, if the reading 64 // system call was interrupted with errno of EINTR, the read operation is 65 // restarted internally without propagating EINTR back to the caller. If there 66 // were no bytes available to be read, this function returns -1 and sets errno 67 // to EWOULDBLOCK. Neither |socket| nor |buf| may be NULL. 68 ssize_t socket_read(const socket_t* socket, void* buf, size_t count); 69 70 // Writes up to |count| bytes from |buf| into |socket|. This function will not 71 // block. Returns a positive integer representing the number of bytes written 72 // to |socket| on success, 0 if the socket has disconnected, and -1 on error. 73 // This function may return a value less than |count| if writing more bytes 74 // would result in blocking. If this function returns -1, errno will also be 75 // set (see send(2) for possible errno values). However, if the writing system 76 // call was interrupted with errno of EINTR, the write operation is restarted 77 // internally without propagating EINTR back to the caller. If no bytes could 78 // be written without blocking, this function will return -1 and set errno to 79 // EWOULDBLOCK. Neither |socket| nor |buf| may be NULL. 80 ssize_t socket_write(const socket_t* socket, const void* buf, size_t count); 81 82 // This function performs the same write operation as |socket_write| and also 83 // sends the file descriptor |fd| over the socket to a remote process. Ownership 84 // of |fd| transfers to this function and the descriptor must not be used any 85 // longer. If |fd| is INVALID_FD, this function behaves the same as 86 // |socket_write|. 87 ssize_t socket_write_and_transfer_fd(const socket_t* socket, const void* buf, 88 size_t count, int fd); 89 90 // Returns the number of bytes that can be read from |socket| without blocking. 91 // On error, this function returns -1. |socket| may not be NULL. 92 // 93 // Note: this function should not be part of the socket interface. It is only 94 // provided as a stop-gap until we can refactor away code that depends on 95 // a priori knowledge of the byte count. Do not use this function unless 96 // you need it while refactoring legacy bluedroid code. 97 ssize_t socket_bytes_available(const socket_t* socket); 98 99 // Registers |socket| with the |reactor|. When the socket becomes readable, 100 // |read_cb| will be called. When the socket becomes writeable, |write_cb| will 101 // be called. The |context| parameter is passed, untouched, to each of the 102 // callback routines. Neither |socket| nor |reactor| may be NULL. |read_cb|, 103 // |write_cb|, and |context| may be NULL. 104 void socket_register(socket_t* socket, reactor_t* reactor, void* context, 105 socket_cb read_cb, socket_cb write_cb); 106 107 // Unregisters |socket| from whichever reactor it is registered with, if any. 108 // This function is idempotent. 109 void socket_unregister(socket_t* socket); 110