CFSocket.h

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