/* * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, * 2018 * Jonathan Schleifer * * All rights reserved. * * This file is part of ObjFW. It may be distributed under the terms of the * Q Public License 1.0, which can be found in the file LICENSE.QPL included in * the packaging of this file. * * Alternatively, it may be distributed under the terms of the GNU General * Public License, either version 2 or 3, which can be found in the file * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFObject.h" #import "OFKernelEventObserver.h" #import "OFRunLoop.h" #import "socket.h" OF_ASSUME_NONNULL_BEGIN /*! @file */ @class OFUDPSocket; #ifdef OF_HAVE_BLOCKS /*! * @brief A block which is called when a packet has been received. * * @param socket The UDP socket which received a packet * @param buffer The buffer the packet has been written to * @param length The length of the packet * @param sender The address of the sender of the packet * @param exception An exception which occurred while receiving or `nil` on * success * @return A bool whether the same block should be used for the next receive */ typedef bool (^of_udp_socket_async_receive_block_t)(OFUDPSocket *socket, void *buffer, size_t length, of_socket_address_t sender, id _Nullable exception); /*! * @brief A block which is called when a packet has been sent. * * @param socket The UDP socket which sent a packet * @param buffer A pointer to the buffer which was sent. This can be changed to * point to a different buffer to be used on the next send. * @param bytesSent The number of bytes which have been sent. This matches the * length specified on the asynchronous send if no exception * was encountered. * @param receiver The receiver for the UDP packet. This may be set to a new * receiver to which the next packet is sent. * @param exception An exception which occurred while reading or `nil` on * success * @return The length to repeat the send with or 0 if it should not repeat. * The buffer and receiver may be changed, so that every time a new * buffer, length and receiver can be specified while the callback * stays the same. */ typedef size_t (^of_udp_socket_async_send_block_t)(OFUDPSocket *socket, const void *_Nonnull *_Nonnull buffer, size_t bytesSent, of_socket_address_t *_Nonnull receiver, id exception); #endif /*! * @protocol OFUDPSocketDelegate OFUDPSocket.h ObjFW/OFUDPSocket.h * * @brief A delegate for OFUDPSocket. */ @protocol OFUDPSocketDelegate @optional /*! * @brief This method is called when a packet has been received. * * @param socket The UDP socket which received a packet * @param buffer The buffer the packet has been written to * @param length The length of the packet * @param sender The address of the sender of the packet * @return A bool whether the same block should be used for the next receive */ - (bool)socket: (OF_KINDOF(OFUDPSocket *))socket didReceiveIntoBuffer: (void *)buffer length: (size_t)length sender: (of_socket_address_t)sender; /*! * @brief This which is called when a packet has been sent. * * @param socket The UDP socket which sent a packet * @param buffer A pointer to the buffer which was sent. This can be changed to * point to a different buffer to be used on the next send. * @param length The length of the buffer that has been sent * @param receiver The receiver for the UDP packet. This may be set to a new * receiver to which the next packet is sent. * @return The length to repeat the send with or 0 if it should not repeat. * The buffer and receiver may be changed, so that every time a new * buffer, length and receiver can be specified while the callback * stays the same. */ - (size_t)socket: (OF_KINDOF(OFUDPSocket *))socket didSendBuffer: (const void *_Nonnull *_Nonnull)buffer length: (size_t)length receiver: (of_socket_address_t *_Nonnull)receiver; /*! * @brief This method is called when an exception occurred during an * asynchronous receive on the socket. * * @param socket The socket for which an exception occurred * @param exception The exception which occurred for the socket */ - (void)socket: (OF_KINDOF(OFUDPSocket *))socket didFailToReceiveWithException: (id)exception; /*! * @brief This method is called when an exception occurred during an * asynchronous send on the socket. * * @param socket The socket for which an exception occurred * @param exception The exception which occurred for the socket */ - (void)socket: (OF_KINDOF(OFUDPSocket *))socket didFailToSendWithException: (id)exception; @end /*! * @class OFUDPSocket OFUDPSocket.h ObjFW/OFUDPSocket.h * * @brief A class which provides methods to create and use UDP sockets. * * Addresses are of type @ref of_socket_address_t. You can use the current * thread's @ref OFDNSResolver to create an address for a host / port pair and * @ref of_socket_address_ip_string to get the IP string / port pair for an * address. If you want to compare two addresses, you can use @ref * of_socket_address_equal and you can use @ref of_socket_address_hash to get a * hash to use in e.g. @ref OFMapTable. * * @warning Even though the OFCopying protocol is implemented, it does *not* * return an independent copy of the socket, but instead retains it. * This is so that the socket can be used as a key for a dictionary, * so context can be associated with a socket. Using a socket in more * than one thread at the same time is not thread-safe, even if copy * was called to create one "instance" for every thread! */ @interface OFUDPSocket: OFObject { of_socket_t _socket; #ifdef OF_WII uint16_t _port; #endif bool _blocking; id _Nullable _delegate; } /*! * @brief Whether the socket is in blocking mode. * * By default, a socket is in blocking mode. */ @property (nonatomic, getter=isBlocking) bool blocking; /*! * @brief The delegate for asynchronous operations on the socket. * * @note The delegate is retained for as long as asynchronous operations are * still outstanding. */ @property OF_NULLABLE_PROPERTY (assign, nonatomic) id delegate; /*! * @brief Returns a new, autoreleased OFUDPSocket. * * @return A new, autoreleased OFUDPSocket */ + (instancetype)socket; /*! * @brief Binds the socket to the specified host and port. * * @param host The host to bind to. Use `@"0.0.0.0"` for IPv4 or `@"::"` for * IPv6 to bind to all. * @param port The port to bind to. If the port is 0, an unused port will be * chosen, which can be obtained using the return value. * @return The port the socket was bound to */ - (uint16_t)bindToHost: (OFString *)host port: (uint16_t)port; /*! * @brief Receives a datagram and stores it into the specified buffer. * * If the buffer is too small, the datagram is truncated. * * @param buffer The buffer to write the datagram to * @param length The length of the buffer * @param sender A pointer to an @ref of_socket_address_t, which will be set to * the address of the sender * @return The length of the received datagram */ - (size_t)receiveIntoBuffer: (void *)buffer length: (size_t)length sender: (of_socket_address_t *)sender; /*! * @brief Asynchronously receives a datagram and stores it into the specified * buffer. * * If the buffer is too small, the datagram is truncated. * * @param buffer The buffer to write the datagram to * @param length The length of the buffer */ - (void)asyncReceiveIntoBuffer: (void *)buffer length: (size_t)length; /*! * @brief Asynchronously receives a datagram and stores it into the specified * buffer. * * If the buffer is too small, the datagram is truncated. * * @param buffer The buffer to write the datagram to * @param length The length of the buffer * @param runLoopMode The run loop mode in which to perform the async receive */ - (void)asyncReceiveIntoBuffer: (void *)buffer length: (size_t)length runLoopMode: (of_run_loop_mode_t)runLoopMode; #ifdef OF_HAVE_BLOCKS /*! * @brief Asynchronously receives a datagram and stores it into the specified * buffer. * * If the buffer is too small, the datagram is truncated. * * @param buffer The buffer to write the datagram to * @param length The length of the buffer * @param block The block to call when the datagram has been received. If the * block returns true, it will be called again with the same * buffer and maximum length when more datagrams have been * received. If you want the next method in the queue to handle * the datagram received next, you need to return false from the * method. */ - (void)asyncReceiveIntoBuffer: (void *)buffer length: (size_t)length block: (of_udp_socket_async_receive_block_t)block; /*! * @brief Asynchronously receives a datagram and stores it into the specified * buffer. * * If the buffer is too small, the datagram is truncated. * * @param buffer The buffer to write the datagram to * @param length The length of the buffer * @param runLoopMode The run loop mode in which to perform the async receive * @param block The block to call when the datagram has been received. If the * block returns true, it will be called again with the same * buffer and maximum length when more datagrams have been * received. If you want the next method in the queue to handle * the datagram received next, you need to return false from the * method. */ - (void)asyncReceiveIntoBuffer: (void *)buffer length: (size_t)length runLoopMode: (of_run_loop_mode_t)runLoopMode block: (of_udp_socket_async_receive_block_t)block; #endif /*! * @brief Sends the specified datagram to the specified address. * * @param buffer The buffer to send as a datagram * @param length The length of the buffer * @param receiver A pointer to an @ref of_socket_address_t to which the * datagram should be sent */ - (void)sendBuffer: (const void *)buffer length: (size_t)length receiver: (const of_socket_address_t *)receiver; /*! * @brief Asynchronously sends the specified datagram to the specified address. * * @param buffer The buffer to send as a datagram * @param length The length of the buffer * @param receiver A pointer to an @ref of_socket_address_t to which the * datagram should be sent */ - (void)asyncSendBuffer: (const void *)buffer length: (size_t)length receiver: (of_socket_address_t)receiver; /*! * @brief Asynchronously sends the specified datagram to the specified address. * * @param buffer The buffer to send as a datagram * @param length The length of the buffer * @param receiver A pointer to an @ref of_socket_address_t to which the * datagram should be sent * @param runLoopMode The run loop mode in which to perform the async send */ - (void)asyncSendBuffer: (const void *)buffer length: (size_t)length receiver: (of_socket_address_t)receiver runLoopMode: (of_run_loop_mode_t)runLoopMode; #ifdef OF_HAVE_BLOCKS /*! * @brief Asynchronously sends the specified datagram to the specified address. * * @param buffer The buffer to send as a datagram * @param length The length of the buffer * @param receiver A pointer to an @ref of_socket_address_t to which the * datagram should be sent * @param block The block to call when the packet has been sent. It should * return the length for the next send with the same callback or 0 * if it should not repeat. The buffer and receiver may be * changed, so that every time a new buffer, length and receiver * can be specified while the callback stays the same. */ - (void)asyncSendBuffer: (const void *)buffer length: (size_t)length receiver: (of_socket_address_t)receiver block: (of_udp_socket_async_send_block_t)block; /*! * @brief Asynchronously sends the specified datagram to the specified address. * * @param buffer The buffer to send as a datagram * @param length The length of the buffer * @param receiver A pointer to an @ref of_socket_address_t to which the * datagram should be sent * @param runLoopMode The run loop mode in which to perform the async send * @param block The block to call when the packet has been sent. It should * return the length for the next send with the same callback or 0 * if it should not repeat. The buffer and receiver may be * changed, so that every time a new buffer, length and receiver * can be specified while the callback stays the same. */ - (void)asyncSendBuffer: (const void *)buffer length: (size_t)length receiver: (of_socket_address_t)receiver runLoopMode: (of_run_loop_mode_t)runLoopMode block: (of_udp_socket_async_send_block_t)block; #endif /*! * @brief Cancels all pending asynchronous requests on the socket. */ - (void)cancelAsyncRequests; /*! * @brief Closes the socket so that it can neither receive nor send any more * datagrams. */ - (void)close; @end #ifdef __cplusplus extern "C" { #endif #ifdef __cplusplus } #endif OF_ASSUME_NONNULL_END