RunLoop.subproj/CFSocket.h

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