CFHTTPServerPriv.h   [plain text]


/*
 * Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
     File:       CFNetwork/CFHTTPServerPriv.h
 
     Contains:   CoreFoundation Network HTTP server SPI
 
     Copyright:   2003-2005 by Apple Computer, Inc., all rights reserved
 
     Warning:    *** APPLE INTERNAL USE ONLY ***
                 This file contains unreleased SPI's
 
     BuildInfo:  Built by:            anonymous
                 On:                  Wed Apr 27 10:45:36 2005
                 With Interfacer:     3.0d46   (Mac OS X for PowerPC)
                 From:                CFHTTPServerPriv.i
                     Revision:        1.7
                     Dated:           2004/06/01 17:53:05
                     Last change by:  rew
                     Last comment:    Updating all copyrights to include 2004
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFHTTPSERVERPRIV__
#define __CFHTTPSERVERPRIV__

#ifndef __CFNETWORKDEFS__
#include <CFNetwork/CFNetworkDefs.h>
#endif

#ifndef __COREFOUNDATION__
#include <CoreFoundation/CoreFoundation.h>
#endif

#ifndef __CFNETWORK__
#include <CFNetwork/CFNetwork.h>
#endif



#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#pragma options align=mac68k

#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint on
#endif


/*
 *  _CFHTTPServerError
 *  
 *  Discussion:
 *    HTTP server's error domain and its errors.
 */
enum _CFHTTPServerError {

  /*
   * CFStreamError domain for HTTP server errors.
   */
  kCFStreamErrorDomainCFHTTPServer = 20,

  /*
   * Critical failure and server should be shutdown and destroyed.
   */
  kCFStreamErrorCFHTTPServerInternal = 1,

  /*
   * A timeout occurred on the given request (and response).
   */
  kCFStreamErrorCFHTTPServerTimeout = 2
};
typedef enum _CFHTTPServerError _CFHTTPServerError;



/*
 *  _CFHTTPServerRef
 *  
 *  Discussion:
 *    This is the type of a reference to a HTTP server.  Although
 *    individual functions are thread-safe, _CFHTTPServerRef itself is
 *    not thread-safe.
 */
typedef struct __CFHTTPServer*          _CFHTTPServerRef;

/*
 *  _CFHTTPServerContext
 *  
 *  Discussion:
 *    Structure containing the user-defined data and callbacks for
 *    _CFHTTPServerRef objects.
 */
struct _CFHTTPServerContext {

  /*
   * The version number of the structure type being passed in as a
   * parameter to the CFHTTPServer creation function. Valid version
   * number is currently 0.
   */
  CFIndex             version;

  /*
   * An arbitrary pointer to client-defined data, which can be
   * associated with the host and is passed to the callbacks.
   */
  void *              info;

  /*
   * The callback used to add a retain for the host on the info pointer
   * for the life of the host, and may be used for temporary references
   * the host needs to take. This callback returns the actual info
   * pointer to store in the host, almost always just the pointer
   * passed as the parameter.
   */
  CFAllocatorRetainCallBack  retain;

  /*
   * The callback used to remove a retain previously added for the host
   * on the info pointer.
   */
  CFAllocatorReleaseCallBack  release;

  /*
   * The callback used to create a descriptive string representation of
   * the info pointer (or the data pointed to by the info pointer) for
   * debugging purposes. This is used by the CFCopyDescription()
   * function.
   */
  CFAllocatorCopyDescriptionCallBack  copyDescription;
};
typedef struct _CFHTTPServerContext     _CFHTTPServerContext;

/*
 *  _CFHTTPServerAcceptNewConnectionCallBack
 *  
 *  Discussion:
 *    Callback which is invoked as a new connection is accepted.
 *  
 *  Parameters:
 *    
 *    server:
 *      The instance of the server which is receiving the connection.
 *    
 *    peer:
 *      A CFDataRef which contains a struct sockaddr holding the peer's
 *      network address.
 *    
 *    info:
 *      The reference from the server context which was given when the
 *      server was created.
 *  
 *  Result:
 *    A boolean value of TRUE if the server should accept the
 *    connection.  FALSE should be returned if the server should deny
 *    the connection.
 */
typedef CALLBACK_API_C( Boolean , _CFHTTPServerAcceptNewConnectionCallBack )(_CFHTTPServerRef server, CFDataRef peer, void *info);

/*
 *  _CFHTTPServerAcceptNewRequestCallBack
 *  
 *  Discussion:
 *    Callback which is invoked as a request begins to arrive.  This
 *    callback will be called after the headers have arrived but before
 *    the body.
 *  
 *  Parameters:
 *    
 *    server:
 *      The instance of the server which is receiving the request.
 *    
 *    headers:
 *      The headers which have been received.
 *    
 *    peer:
 *      A CFDataRef which contains a struct sockaddr holding the peer's
 *      network address.
 *    
 *    info:
 *      The reference from the server context which was given when the
 *      server was created.
 *  
 *  Result:
 *    A boolean value of TRUE if the server should accept the request. 
 *    FALSE should be returned if the server should deny the request. 
 *    All requests on the outstanding connection will be cancelled too.
 */
typedef CALLBACK_API_C( Boolean , _CFHTTPServerAcceptNewRequestCallBack )(_CFHTTPServerRef server, CFHTTPMessageRef headers, CFDataRef peer, void *info);

/*
 *  _CFHTTPServerDidReceiveRequestCallBack
 *  
 *  Discussion:
 *    Callback which is invoked when a request has been successfully
 *    received.
 *  
 *  Parameters:
 *    
 *    server:
 *      The instance of the server which received the given request.
 *    
 *    request:
 *      The request which was received.  Use this request in order to
 *      add a response.
 *    
 *    info:
 *      The reference from the server context which was given when the
 *      server was created.
 */
typedef CALLBACK_API_C( void , _CFHTTPServerDidReceiveRequestCallBack )(_CFHTTPServerRef server, CFHTTPMessageRef request, void *info);

/*
 *  _CFHTTPServerDidSendResponseCallBack
 *  
 *  Discussion:
 *    Callback which is invoked when an individual response has been
 *    successfully sent.
 *  
 *  Parameters:
 *    
 *    server:
 *      The instance of the server with which the request and response
 *      were associated.
 *    
 *    request:
 *      The original request with which the response was associated.
 *    
 *    response:
 *      The massaged response which was sent over the wire.  This is a
 *      copy of the original response and has no body.  It is just the
 *      headers.
 *    
 *    info:
 *      The reference from the server context which was given when the
 *      server was created.
 */
typedef CALLBACK_API_C( void , _CFHTTPServerDidSendResponseCallBack )(_CFHTTPServerRef server, CFHTTPMessageRef request, CFHTTPMessageRef response, void *info);

/*
 *  _CFHTTPServerErrorCallBack
 *  
 *  Discussion:
 *    Callback which is invoked when errors occur in the server.  All
 *    requests and responses on a single persistent connection will
 *    receive the error at the same time if it was the connection
 *    itself which had the error.
 *  
 *  Parameters:
 *    
 *    server:
 *      The instance of the server which received the error.
 *    
 *    error:
 *      Reference to the CFStreamError which contains the error
 *      information.
 *    
 *    request:
 *      If non-NULL, the request which was being actively managed when
 *      the error was received.
 *    
 *    response:
 *      If non-NULL, the response which was being actively managed when
 *      the error was received.
 *    
 *    info:
 *      The reference from the server context which was given when the
 *      server was created.
 */
typedef CALLBACK_API_C( void , _CFHTTPServerErrorCallBack )(_CFHTTPServerRef server, const CFStreamError *error, CFHTTPMessageRef request, CFHTTPMessageRef response, void *info);

/*
 *  _CFHTTPServerCallBacks
 *  
 *  Discussion:
 *    The set of callbacks which will be invoked as different events
 *    occur inside of the server.
 */
struct _CFHTTPServerCallBacks {

  /*
   * The version number of the structure type being passed in as a
   * parameter to the CFHTTPServer creation function. Valid version
   * number is currently 0.
   */
  CFIndex             version;

  /*
   * Callback invoked when a new incoming connection is accepted.
   */
  _CFHTTPServerAcceptNewConnectionCallBack  acceptNewConnectionCallBack;

  /*
   * Callback invoked when a new incoming request has started but after
   * the headers have arrived.
   */
  _CFHTTPServerAcceptNewRequestCallBack  acceptNewRequestCallBack;

  /*
   * Callback invoked when a full request has been received.
   */
  _CFHTTPServerDidReceiveRequestCallBack  didReceiveRequestCallBack;

  /*
   * Callback invoked when an individual response has been completely
   * sent.
   */
  _CFHTTPServerDidSendResponseCallBack  didSendResponseCallBack;

  /*
   * Callback invoked if there is an error on the server.
   */
  _CFHTTPServerErrorCallBack  errorCallBack;
};
typedef struct _CFHTTPServerCallBacks   _CFHTTPServerCallBacks;
/*
 *  _CFHTTPServerGetTypeID()
 *  
 *  Discussion:
 *    Returns the type identifier of all _CFHTTPServer instances.
 *  
 *  Mac OS X threading:
 *    Not thread safe
 *  
 */
extern CFTypeID 
_CFHTTPServerGetTypeID(void)                                  AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerCreate()
 *  
 *  Discussion:
 *    Creates a new HTTP server.
 *  
 *  Mac OS X threading:
 *    Not thread safe
 *  
 *  Parameters:
 *    
 *    alloc:
 *      The CFAllocator which should be used to allocate memory for the
 *      server. If this reference is not a valid CFAllocator, the
 *      behavior is undefined.
 *    
 *    callbacks:
 *      The callbacks which should be called as requests and responses
 *      are handled or if errors occur.
 *    
 *    context:
 *      A _CFHTTPServerContext which is used to set the contextual
 *      information associated with the server object. The info pointer
 *      from the struct will be passed to the callback function.
 *  
 *  Result:
 *    Returns NULL if unsuccessful, otherwise a _CFHTTPServerRef will
 *    be returned.
 *  
 */
extern _CFHTTPServerRef 
_CFHTTPServerCreate(
  CFAllocatorRef                  alloc,
  const _CFHTTPServerCallBacks *  callbacks,
  _CFHTTPServerContext *          context)                    AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerStart()
 *  
 *  Discussion:
 *    Starts the server listening and handling incoming connections on
 *    the given port.  It also Rendezvous advertises itself on the
 *    local domain with the given name and type if provided.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server being started.  Must be non-NULL. If this reference
 *      is not a valid _CFHTTPServerRef, the behavior is undefined.
 *    
 *    name:
 *      The name to use for Rendezvous advertising.  The empty string
 *      or NULL indicate to use the machine's name.
 *    
 *    serviceType:
 *      The type of service being advertised on Rendezvous. If the
 *      service type and name are both NULL, the server will not
 *      Rendezvous advertise itself.
 *    
 *    port:
 *      The port on which the server should be listening for new
 *      connections.  Use zero to indicate that the server can assign
 *      one for the service (use this is a well-known port has not been
 *      assigned).
 *  
 *  Result:
 *    Returns TRUE is the server was started.  It returns FALSE if
 *    there was a failure to start the server.
 *  
 */
extern Boolean 
_CFHTTPServerStart(
  _CFHTTPServerRef   server,
  CFStringRef        name,
  CFStringRef        serviceType,
  UInt32             port)                                    AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerInvalidate()
 *  
 *  Discussion:
 *    Invalidates the server, so that it no longer accepts connections
 *    and the client will no longer receive callbacks. All outstanding
 *    requests/responses are terminated.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server being invalidated.  Must be non-NULL. If this
 *      reference is not a valid _CFHTTPServerRef, the behavior is
 *      undefined.
 *  
 */
extern void 
_CFHTTPServerInvalidate(_CFHTTPServerRef server)              AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerGetPort()
 *  
 *  Discussion:
 *    Returns the port on which the server is listening. If not
 *    currently listening, it will return zero.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server being queried.  Must be non-NULL. If this reference
 *      is not a valid _CFHTTPServerRef, the behavior is undefined.
 *  
 */
extern UInt32 
_CFHTTPServerGetPort(_CFHTTPServerRef server)                 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerCopyPeerAddressForRequest()
 *  
 *  Discussion:
 *    Given an incoming request, this function will retrieve the peer's
 *    address.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server which received the request.
 *    
 *    request:
 *      The incoming request whose peer wishes to be known.
 *  
 *  Result:
 *    Returns a CFDataRef which contains a struct sockaddr holding the
 *    address of the peer.  NULL is returned if not known.
 *  
 */
extern CFDataRef 
_CFHTTPServerCopyPeerAddressForRequest(
  _CFHTTPServerRef   server,
  CFHTTPMessageRef   request)                                 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerAddResponse()
 *  
 *  Discussion:
 *    Adds the given response for the request to the server. Only one
 *    response should be added per individual request.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server on which the request was received.  Must be
 *      non-NULL.  If this reference is not a valid _CFHTTPServerRef,
 *      the behavior is undefined.
 *    
 *    request:
 *      The request which was received and for which the response being
 *      added corresponds.
 *    
 *    response:
 *      The response being added for the given request.
 *  
 */
extern void 
_CFHTTPServerAddResponse(
  _CFHTTPServerRef   server,
  CFHTTPMessageRef   request,
  CFHTTPMessageRef   response)                                AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  _CFHTTPServerAddStreamedResponse()
 *  
 *  Discussion:
 *    Adds the given response headers and body for the request to the
 *    server.  Only one response should be added per individual request.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    server:
 *      The server on which the request was received.  Must be
 *      non-NULL.  If this reference is not a valid _CFHTTPServerRef,
 *      the behavior is undefined.
 *    
 *    request:
 *      The request which was received and for which the response being
 *      added corresponds.
 *    
 *    responseHeaders:
 *      The headers for the response being added.
 *    
 *    body:
 *      An unopened CFReadStreamRef which will be used for stream- ing
 *      the body's data to the requesting client.
 *  
 */
extern void 
_CFHTTPServerAddStreamedResponse(
  _CFHTTPServerRef   server,
  CFHTTPMessageRef   request,
  CFHTTPMessageRef   responseHeaders,
  CFReadStreamRef    body)                                    AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#pragma options align=reset

#ifdef __cplusplus
}
#endif

#endif /* __CFHTTPSERVERPRIV__ */