socket.h revision d2199cbb8f361772819402b56e6fa46587a31c56
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 also 62// be set (see recv(2) for possible errno values). If there were no bytes available 63// to be read, this function returns -1 and sets errno to EWOULDBLOCK. Neither 64// |socket| nor |buf| may be NULL. 65ssize_t socket_read(const socket_t *socket, void *buf, size_t count); 66 67// Writes up to |count| bytes from |buf| into |socket|. This function will not 68// block. Returns a positive integer representing the number of bytes written 69// to |socket| on success, 0 if the socket has disconnected, and -1 on error. This 70// function may return a value less than |count| if writing more bytes would result 71// in blocking. If this function returns -1, errno will also be set (see send(2) for 72// possible errno values). If no bytes could be written without blocking, this 73// function will return -1 and set errno to EWOULDBLOCK. Neither |socket| nor |buf| 74// may be NULL. 75ssize_t socket_write(const socket_t *socket, const void *buf, size_t count); 76 77// This function performs the same write operation as |socket_write| and also 78// sends the file descriptor |fd| over the socket to a remote process. Ownership 79// of |fd| transfers to this function and the descriptor must not be used any longer. 80// If |fd| is INVALID_FD, this function behaves the same as |socket_write|. 81ssize_t socket_write_and_transfer_fd(const socket_t *socket, const void *buf, size_t count, int fd); 82 83// Returns the number of bytes that can be read from |socket| without blocking. On error, 84// this function returns -1. |socket| may not be NULL. 85// 86// Note: this function should not be part of the socket interface. It is only provided as 87// a stop-gap until we can refactor away code that depends on a priori knowledge of 88// the byte count. Do not use this function unless you need it while refactoring 89// legacy bluedroid code. 90ssize_t socket_bytes_available(const socket_t *socket); 91 92// Registers |socket| with the |reactor|. When the socket becomes readable, |read_cb| 93// will be called. When the socket becomes writeable, |write_cb| will be called. The 94// |context| parameter is passed, untouched, to each of the callback routines. Neither 95// |socket| nor |reactor| may be NULL. |read_cb|, |write_cb|, and |context| may be NULL. 96void socket_register(socket_t *socket, reactor_t *reactor, void *context, socket_cb read_cb, socket_cb write_cb); 97 98// Unregisters |socket| from whichever reactor it is registered with, if any. This 99// function is idempotent. 100void socket_unregister(socket_t *socket); 101