1/* 2 * Copyright (c) 2014 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/* CFSocket.h 25 Copyright (c) 1999-2013, Apple Inc. All rights reserved. 26*/ 27 28#if !defined(__COREFOUNDATION_CFSOCKET__) 29#define __COREFOUNDATION_CFSOCKET__ 1 30 31#include <CoreFoundation/CFRunLoop.h> 32#include <CoreFoundation/CFData.h> 33 34CF_EXTERN_C_BEGIN 35 36typedef struct __CFSocket * CFSocketRef; 37 38/* A CFSocket contains a native socket within a structure that can 39be used to read from the socket in the background and make the data 40thus read available using a runloop source. The callback used for 41this may be of three types, as specified by the callBackTypes 42argument when creating the CFSocket. 43 44If kCFSocketReadCallBack is used, then data will not be 45automatically read, but the callback will be called when data 46is available to be read, or a new child socket is waiting to be 47accepted. 48 49If kCFSocketAcceptCallBack is used, then new child sockets will be 50accepted and passed to the callback, with the data argument being 51a pointer to a CFSocketNativeHandle. This is usable only with 52connection rendezvous sockets. 53 54If kCFSocketDataCallBack is used, then data will be read in chunks 55in the background and passed to the callback, with the data argument 56being a CFDataRef. 57 58These three types are mutually exclusive, but any one of them may 59have kCFSocketConnectCallBack added to it, if the socket will be 60used to connect in the background. Connect in the background occurs 61if CFSocketConnectToAddress is called with a negative timeout 62value, in which case the call returns immediately, and a 63kCFSocketConnectCallBack is generated when the connect finishes. 64In this case the data argument is either NULL, or a pointer to 65an SInt32 error code if the connect failed. kCFSocketConnectCallBack 66will never be sent more than once for a given socket. 67 68The callback types may also have kCFSocketWriteCallBack added to 69them, if large amounts of data are to be sent rapidly over the 70socket and notification is desired when there is space in the 71kernel buffers so that the socket is writable again. 72 73With a connection-oriented socket, if the connection is broken from the 74other end, then one final kCFSocketReadCallBack or kCFSocketDataCallBack 75will occur. In the case of kCFSocketReadCallBack, the underlying socket 76will have 0 bytes available to read. In the case of kCFSocketDataCallBack, 77the data argument will be a CFDataRef of length 0. 78 79There are socket flags that may be set to control whether callbacks of 80a given type are automatically reenabled after they are triggered, and 81whether the underlying native socket will be closed when the CFSocket 82is invalidated. By default read, accept, and data callbacks are 83automatically reenabled; write callbacks are not, and connect callbacks 84may not be, since they are sent once only. Be careful about automatically 85reenabling read and write callbacks, since this implies that the 86callbacks will be sent repeatedly if the socket remains readable or 87writable respectively. Be sure to set these flags only for callbacks 88that your CFSocket actually possesses; the result of setting them for 89other callback types is undefined. 90 91Individual callbacks may also be enabled and disabled manually, whether 92they are automatically reenabled or not. If they are not automatically 93reenabled, then they will need to be manually reenabled when the callback 94is ready to be received again (and not sooner). Even if they are 95automatically reenabled, there may be occasions when it will be useful 96to be able to manually disable them temporarily and then reenable them. 97Be sure to enable and disable only callbacks that your CFSocket actually 98possesses; the result of enabling and disabling other callback types is 99undefined. 100 101By default the underlying native socket will be closed when the CFSocket 102is invalidated, but it will not be if kCFSocketCloseOnInvalidate is 103turned off. This can be useful in order to destroy a CFSocket but 104continue to use the underlying native socket. The CFSocket must 105still be invalidated when it will no longer be used. Do not in 106either case close the underlying native socket without invalidating 107the CFSocket. 108 109Addresses are stored as CFDatas containing a struct sockaddr 110appropriate for the protocol family; make sure that all fields are 111filled in properly when passing in an address. 112 113*/ 114 115/* Values for CFSocketError */ 116typedef CF_ENUM(CFIndex, CFSocketError) { 117 kCFSocketSuccess = 0, 118 kCFSocketError = -1L, 119 kCFSocketTimeout = -2L 120}; 121 122typedef struct { 123 SInt32 protocolFamily; 124 SInt32 socketType; 125 SInt32 protocol; 126 CFDataRef address; 127} CFSocketSignature; 128 129/* Values for CFSocketCallBackType */ 130typedef CF_OPTIONS(CFOptionFlags, CFSocketCallBackType) { 131 kCFSocketNoCallBack = 0, 132 kCFSocketReadCallBack = 1, 133 kCFSocketAcceptCallBack = 2, 134 kCFSocketDataCallBack = 3, 135 kCFSocketConnectCallBack = 4, 136 kCFSocketWriteCallBack = 8 137}; 138 139/* Socket flags */ 140enum { 141 kCFSocketAutomaticallyReenableReadCallBack = 1, 142 kCFSocketAutomaticallyReenableAcceptCallBack = 2, 143 kCFSocketAutomaticallyReenableDataCallBack = 3, 144 kCFSocketAutomaticallyReenableWriteCallBack = 8, 145 kCFSocketLeaveErrors CF_ENUM_AVAILABLE(10_5, 2_0) = 64, 146 kCFSocketCloseOnInvalidate = 128 147}; 148 149typedef void (*CFSocketCallBack)(CFSocketRef s, CFSocketCallBackType type, CFDataRef address, const void *data, void *info); 150/* If the callback wishes to keep hold of address or data after the point that it returns, then it must copy them. */ 151 152typedef struct { 153 CFIndex version; 154 void * info; 155 const void *(*retain)(const void *info); 156 void (*release)(const void *info); 157 CFStringRef (*copyDescription)(const void *info); 158} CFSocketContext; 159 160#if TARGET_OS_WIN32 161typedef uintptr_t CFSocketNativeHandle; 162#else 163typedef int CFSocketNativeHandle; 164#endif 165 166CF_EXPORT CFTypeID CFSocketGetTypeID(void); 167 168CF_EXPORT CFSocketRef CFSocketCreate(CFAllocatorRef allocator, SInt32 protocolFamily, SInt32 socketType, SInt32 protocol, CFOptionFlags callBackTypes, CFSocketCallBack callout, const CFSocketContext *context); 169CF_EXPORT CFSocketRef CFSocketCreateWithNative(CFAllocatorRef allocator, CFSocketNativeHandle sock, CFOptionFlags callBackTypes, CFSocketCallBack callout, const CFSocketContext *context); 170CF_EXPORT CFSocketRef CFSocketCreateWithSocketSignature(CFAllocatorRef allocator, const CFSocketSignature *signature, CFOptionFlags callBackTypes, CFSocketCallBack callout, const CFSocketContext *context); 171/* CFSocketCreateWithSocketSignature() creates a socket of the requested type and binds its address (using CFSocketSetAddress()) to the requested address. If this fails, it returns NULL. */ 172CF_EXPORT CFSocketRef CFSocketCreateConnectedToSocketSignature(CFAllocatorRef allocator, const CFSocketSignature *signature, CFOptionFlags callBackTypes, CFSocketCallBack callout, const CFSocketContext *context, CFTimeInterval timeout); 173/* CFSocketCreateConnectedToSocketSignature() creates a socket suitable for connecting to the requested type and address, and connects it (using CFSocketConnectToAddress()). If this fails, it returns NULL. */ 174 175CF_EXPORT CFSocketError CFSocketSetAddress(CFSocketRef s, CFDataRef address); 176CF_EXPORT CFSocketError CFSocketConnectToAddress(CFSocketRef s, CFDataRef address, CFTimeInterval timeout); 177CF_EXPORT void CFSocketInvalidate(CFSocketRef s); 178 179CF_EXPORT Boolean CFSocketIsValid(CFSocketRef s); 180CF_EXPORT CFDataRef CFSocketCopyAddress(CFSocketRef s); 181CF_EXPORT CFDataRef CFSocketCopyPeerAddress(CFSocketRef s); 182CF_EXPORT void CFSocketGetContext(CFSocketRef s, CFSocketContext *context); 183CF_EXPORT CFSocketNativeHandle CFSocketGetNative(CFSocketRef s); 184 185CF_EXPORT CFRunLoopSourceRef CFSocketCreateRunLoopSource(CFAllocatorRef allocator, CFSocketRef s, CFIndex order); 186 187CF_EXPORT CFOptionFlags CFSocketGetSocketFlags(CFSocketRef s); 188CF_EXPORT void CFSocketSetSocketFlags(CFSocketRef s, CFOptionFlags flags); 189CF_EXPORT void CFSocketDisableCallBacks(CFSocketRef s, CFOptionFlags callBackTypes); 190CF_EXPORT void CFSocketEnableCallBacks(CFSocketRef s, CFOptionFlags callBackTypes); 191 192 193/* For convenience, a function is provided to send data using the socket with a timeout. The timeout will be used only if the specified value is positive. The address should be left NULL if the socket is already connected. */ 194CF_EXPORT CFSocketError CFSocketSendData(CFSocketRef s, CFDataRef address, CFDataRef data, CFTimeInterval timeout); 195 196/* Generic name registry functionality (CFSocketRegisterValue, 197CFSocketCopyRegisteredValue) allows the registration of any property 198list type. Functions specific to CFSockets (CFSocketRegisterSocketData, 199CFSocketCopyRegisteredSocketData) register a CFData containing the 200components of a socket signature (protocol family, socket type, 201protocol, and address). In each function the nameServerSignature 202may be NULL, or any component of it may be 0, to use default values 203(TCP, INADDR_LOOPBACK, port as set). Name registration servers might 204not allow registration with other than TCP and INADDR_LOOPBACK. 205The actual address of the server responding to a query may be obtained 206by using the nameServerAddress argument. This address, the address 207returned by CFSocketCopyRegisteredSocketSignature, and the value 208returned by CFSocketCopyRegisteredValue must (if non-null) be released 209by the caller. CFSocketUnregister removes any registration associated 210with the specified name. 211*/ 212 213CF_EXPORT CFSocketError CFSocketRegisterValue(const CFSocketSignature *nameServerSignature, CFTimeInterval timeout, CFStringRef name, CFPropertyListRef value); 214CF_EXPORT CFSocketError CFSocketCopyRegisteredValue(const CFSocketSignature *nameServerSignature, CFTimeInterval timeout, CFStringRef name, CFPropertyListRef *value, CFDataRef *nameServerAddress); 215 216CF_EXPORT CFSocketError CFSocketRegisterSocketSignature(const CFSocketSignature *nameServerSignature, CFTimeInterval timeout, CFStringRef name, const CFSocketSignature *signature); 217CF_EXPORT CFSocketError CFSocketCopyRegisteredSocketSignature(const CFSocketSignature *nameServerSignature, CFTimeInterval timeout, CFStringRef name, CFSocketSignature *signature, CFDataRef *nameServerAddress); 218 219CF_EXPORT CFSocketError CFSocketUnregister(const CFSocketSignature *nameServerSignature, CFTimeInterval timeout, CFStringRef name); 220 221CF_EXPORT void CFSocketSetDefaultNameRegistryPortNumber(UInt16 port); 222CF_EXPORT UInt16 CFSocketGetDefaultNameRegistryPortNumber(void); 223 224/* Constants used in name registry server communications */ 225CF_EXPORT const CFStringRef kCFSocketCommandKey; 226CF_EXPORT const CFStringRef kCFSocketNameKey; 227CF_EXPORT const CFStringRef kCFSocketValueKey; 228CF_EXPORT const CFStringRef kCFSocketResultKey; 229CF_EXPORT const CFStringRef kCFSocketErrorKey; 230CF_EXPORT const CFStringRef kCFSocketRegisterCommand; 231CF_EXPORT const CFStringRef kCFSocketRetrieveCommand; 232 233CF_EXTERN_C_END 234 235#endif /* ! __COREFOUNDATION_CFSOCKET__ */ 236 237