build-mac/curl/multi.h
author Krista Bennett <krista@pep-project.org>
Tue, 02 Oct 2018 13:22:12 +0200
branchENGINE-463
changeset 2964 4f22b5bc7b9a
parent 531 a7cc26cc39f2
permissions -rw-r--r--
Stupid syntax error.
     1 #ifndef __CURL_MULTI_H
     2 #define __CURL_MULTI_H
     3 /***************************************************************************
     4  *                                  _   _ ____  _
     5  *  Project                     ___| | | |  _ \| |
     6  *                             / __| | | | |_) | |
     7  *                            | (__| |_| |  _ <| |___
     8  *                             \___|\___/|_| \_\_____|
     9  *
    10  * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
    11  *
    12  * This software is licensed as described in the file COPYING, which
    13  * you should have received as part of this distribution. The terms
    14  * are also available at https://curl.haxx.se/docs/copyright.html.
    15  *
    16  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
    17  * copies of the Software, and permit persons to whom the Software is
    18  * furnished to do so, under the terms of the COPYING file.
    19  *
    20  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
    21  * KIND, either express or implied.
    22  *
    23  ***************************************************************************/
    24 /*
    25   This is an "external" header file. Don't give away any internals here!
    26 
    27   GOALS
    28 
    29   o Enable a "pull" interface. The application that uses libcurl decides where
    30     and when to ask libcurl to get/send data.
    31 
    32   o Enable multiple simultaneous transfers in the same thread without making it
    33     complicated for the application.
    34 
    35   o Enable the application to select() on its own file descriptors and curl's
    36     file descriptors simultaneous easily.
    37 
    38 */
    39 
    40 /*
    41  * This header file should not really need to include "curl.h" since curl.h
    42  * itself includes this file and we expect user applications to do #include
    43  * <curl/curl.h> without the need for especially including multi.h.
    44  *
    45  * For some reason we added this include here at one point, and rather than to
    46  * break existing (wrongly written) libcurl applications, we leave it as-is
    47  * but with this warning attached.
    48  */
    49 #include "curl.h"
    50 
    51 #ifdef  __cplusplus
    52 extern "C" {
    53 #endif
    54 
    55 typedef void CURLM;
    56 
    57 typedef enum {
    58   CURLM_CALL_MULTI_PERFORM = -1, /* please call curl_multi_perform() or
    59                                     curl_multi_socket*() soon */
    60   CURLM_OK,
    61   CURLM_BAD_HANDLE,      /* the passed-in handle is not a valid CURLM handle */
    62   CURLM_BAD_EASY_HANDLE, /* an easy handle was not good/valid */
    63   CURLM_OUT_OF_MEMORY,   /* if you ever get this, you're in deep sh*t */
    64   CURLM_INTERNAL_ERROR,  /* this is a libcurl bug */
    65   CURLM_BAD_SOCKET,      /* the passed in socket argument did not match */
    66   CURLM_UNKNOWN_OPTION,  /* curl_multi_setopt() with unsupported option */
    67   CURLM_ADDED_ALREADY,   /* an easy handle already added to a multi handle was
    68                             attempted to get added - again */
    69   CURLM_LAST
    70 } CURLMcode;
    71 
    72 /* just to make code nicer when using curl_multi_socket() you can now check
    73    for CURLM_CALL_MULTI_SOCKET too in the same style it works for
    74    curl_multi_perform() and CURLM_CALL_MULTI_PERFORM */
    75 #define CURLM_CALL_MULTI_SOCKET CURLM_CALL_MULTI_PERFORM
    76 
    77 /* bitmask bits for CURLMOPT_PIPELINING */
    78 #define CURLPIPE_NOTHING   0L
    79 #define CURLPIPE_HTTP1     1L
    80 #define CURLPIPE_MULTIPLEX 2L
    81 
    82 typedef enum {
    83   CURLMSG_NONE, /* first, not used */
    84   CURLMSG_DONE, /* This easy handle has completed. 'result' contains
    85                    the CURLcode of the transfer */
    86   CURLMSG_LAST /* last, not used */
    87 } CURLMSG;
    88 
    89 struct CURLMsg {
    90   CURLMSG msg;       /* what this message means */
    91   CURL *easy_handle; /* the handle it concerns */
    92   union {
    93     void *whatever;    /* message-specific data */
    94     CURLcode result;   /* return code for transfer */
    95   } data;
    96 };
    97 typedef struct CURLMsg CURLMsg;
    98 
    99 /* Based on poll(2) structure and values.
   100  * We don't use pollfd and POLL* constants explicitly
   101  * to cover platforms without poll(). */
   102 #define CURL_WAIT_POLLIN    0x0001
   103 #define CURL_WAIT_POLLPRI   0x0002
   104 #define CURL_WAIT_POLLOUT   0x0004
   105 
   106 struct curl_waitfd {
   107   curl_socket_t fd;
   108   short events;
   109   short revents; /* not supported yet */
   110 };
   111 
   112 /*
   113  * Name:    curl_multi_init()
   114  *
   115  * Desc:    inititalize multi-style curl usage
   116  *
   117  * Returns: a new CURLM handle to use in all 'curl_multi' functions.
   118  */
   119 CURL_EXTERN CURLM *curl_multi_init(void);
   120 
   121 /*
   122  * Name:    curl_multi_add_handle()
   123  *
   124  * Desc:    add a standard curl handle to the multi stack
   125  *
   126  * Returns: CURLMcode type, general multi error code.
   127  */
   128 CURL_EXTERN CURLMcode curl_multi_add_handle(CURLM *multi_handle,
   129                                             CURL *curl_handle);
   130 
   131  /*
   132   * Name:    curl_multi_remove_handle()
   133   *
   134   * Desc:    removes a curl handle from the multi stack again
   135   *
   136   * Returns: CURLMcode type, general multi error code.
   137   */
   138 CURL_EXTERN CURLMcode curl_multi_remove_handle(CURLM *multi_handle,
   139                                                CURL *curl_handle);
   140 
   141  /*
   142   * Name:    curl_multi_fdset()
   143   *
   144   * Desc:    Ask curl for its fd_set sets. The app can use these to select() or
   145   *          poll() on. We want curl_multi_perform() called as soon as one of
   146   *          them are ready.
   147   *
   148   * Returns: CURLMcode type, general multi error code.
   149   */
   150 CURL_EXTERN CURLMcode curl_multi_fdset(CURLM *multi_handle,
   151                                        fd_set *read_fd_set,
   152                                        fd_set *write_fd_set,
   153                                        fd_set *exc_fd_set,
   154                                        int *max_fd);
   155 
   156 /*
   157  * Name:     curl_multi_wait()
   158  *
   159  * Desc:     Poll on all fds within a CURLM set as well as any
   160  *           additional fds passed to the function.
   161  *
   162  * Returns:  CURLMcode type, general multi error code.
   163  */
   164 CURL_EXTERN CURLMcode curl_multi_wait(CURLM *multi_handle,
   165                                       struct curl_waitfd extra_fds[],
   166                                       unsigned int extra_nfds,
   167                                       int timeout_ms,
   168                                       int *ret);
   169 
   170  /*
   171   * Name:    curl_multi_perform()
   172   *
   173   * Desc:    When the app thinks there's data available for curl it calls this
   174   *          function to read/write whatever there is right now. This returns
   175   *          as soon as the reads and writes are done. This function does not
   176   *          require that there actually is data available for reading or that
   177   *          data can be written, it can be called just in case. It returns
   178   *          the number of handles that still transfer data in the second
   179   *          argument's integer-pointer.
   180   *
   181   * Returns: CURLMcode type, general multi error code. *NOTE* that this only
   182   *          returns errors etc regarding the whole multi stack. There might
   183   *          still have occurred problems on invidual transfers even when this
   184   *          returns OK.
   185   */
   186 CURL_EXTERN CURLMcode curl_multi_perform(CURLM *multi_handle,
   187                                          int *running_handles);
   188 
   189  /*
   190   * Name:    curl_multi_cleanup()
   191   *
   192   * Desc:    Cleans up and removes a whole multi stack. It does not free or
   193   *          touch any individual easy handles in any way. We need to define
   194   *          in what state those handles will be if this function is called
   195   *          in the middle of a transfer.
   196   *
   197   * Returns: CURLMcode type, general multi error code.
   198   */
   199 CURL_EXTERN CURLMcode curl_multi_cleanup(CURLM *multi_handle);
   200 
   201 /*
   202  * Name:    curl_multi_info_read()
   203  *
   204  * Desc:    Ask the multi handle if there's any messages/informationals from
   205  *          the individual transfers. Messages include informationals such as
   206  *          error code from the transfer or just the fact that a transfer is
   207  *          completed. More details on these should be written down as well.
   208  *
   209  *          Repeated calls to this function will return a new struct each
   210  *          time, until a special "end of msgs" struct is returned as a signal
   211  *          that there is no more to get at this point.
   212  *
   213  *          The data the returned pointer points to will not survive calling
   214  *          curl_multi_cleanup().
   215  *
   216  *          The 'CURLMsg' struct is meant to be very simple and only contain
   217  *          very basic informations. If more involved information is wanted,
   218  *          we will provide the particular "transfer handle" in that struct
   219  *          and that should/could/would be used in subsequent
   220  *          curl_easy_getinfo() calls (or similar). The point being that we
   221  *          must never expose complex structs to applications, as then we'll
   222  *          undoubtably get backwards compatibility problems in the future.
   223  *
   224  * Returns: A pointer to a filled-in struct, or NULL if it failed or ran out
   225  *          of structs. It also writes the number of messages left in the
   226  *          queue (after this read) in the integer the second argument points
   227  *          to.
   228  */
   229 CURL_EXTERN CURLMsg *curl_multi_info_read(CURLM *multi_handle,
   230                                           int *msgs_in_queue);
   231 
   232 /*
   233  * Name:    curl_multi_strerror()
   234  *
   235  * Desc:    The curl_multi_strerror function may be used to turn a CURLMcode
   236  *          value into the equivalent human readable error string.  This is
   237  *          useful for printing meaningful error messages.
   238  *
   239  * Returns: A pointer to a zero-terminated error message.
   240  */
   241 CURL_EXTERN const char *curl_multi_strerror(CURLMcode);
   242 
   243 /*
   244  * Name:    curl_multi_socket() and
   245  *          curl_multi_socket_all()
   246  *
   247  * Desc:    An alternative version of curl_multi_perform() that allows the
   248  *          application to pass in one of the file descriptors that have been
   249  *          detected to have "action" on them and let libcurl perform.
   250  *          See man page for details.
   251  */
   252 #define CURL_POLL_NONE   0
   253 #define CURL_POLL_IN     1
   254 #define CURL_POLL_OUT    2
   255 #define CURL_POLL_INOUT  3
   256 #define CURL_POLL_REMOVE 4
   257 
   258 #define CURL_SOCKET_TIMEOUT CURL_SOCKET_BAD
   259 
   260 #define CURL_CSELECT_IN   0x01
   261 #define CURL_CSELECT_OUT  0x02
   262 #define CURL_CSELECT_ERR  0x04
   263 
   264 typedef int (*curl_socket_callback)(CURL *easy,      /* easy handle */
   265                                     curl_socket_t s, /* socket */
   266                                     int what,        /* see above */
   267                                     void *userp,     /* private callback
   268                                                         pointer */
   269                                     void *socketp);  /* private socket
   270                                                         pointer */
   271 /*
   272  * Name:    curl_multi_timer_callback
   273  *
   274  * Desc:    Called by libcurl whenever the library detects a change in the
   275  *          maximum number of milliseconds the app is allowed to wait before
   276  *          curl_multi_socket() or curl_multi_perform() must be called
   277  *          (to allow libcurl's timed events to take place).
   278  *
   279  * Returns: The callback should return zero.
   280  */
   281 typedef int (*curl_multi_timer_callback)(CURLM *multi,    /* multi handle */
   282                                          long timeout_ms, /* see above */
   283                                          void *userp);    /* private callback
   284                                                              pointer */
   285 
   286 CURL_EXTERN CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t s,
   287                                         int *running_handles);
   288 
   289 CURL_EXTERN CURLMcode curl_multi_socket_action(CURLM *multi_handle,
   290                                                curl_socket_t s,
   291                                                int ev_bitmask,
   292                                                int *running_handles);
   293 
   294 CURL_EXTERN CURLMcode curl_multi_socket_all(CURLM *multi_handle,
   295                                             int *running_handles);
   296 
   297 #ifndef CURL_ALLOW_OLD_MULTI_SOCKET
   298 /* This macro below was added in 7.16.3 to push users who recompile to use
   299    the new curl_multi_socket_action() instead of the old curl_multi_socket()
   300 */
   301 #define curl_multi_socket(x,y,z) curl_multi_socket_action(x,y,0,z)
   302 #endif
   303 
   304 /*
   305  * Name:    curl_multi_timeout()
   306  *
   307  * Desc:    Returns the maximum number of milliseconds the app is allowed to
   308  *          wait before curl_multi_socket() or curl_multi_perform() must be
   309  *          called (to allow libcurl's timed events to take place).
   310  *
   311  * Returns: CURLM error code.
   312  */
   313 CURL_EXTERN CURLMcode curl_multi_timeout(CURLM *multi_handle,
   314                                          long *milliseconds);
   315 
   316 #undef CINIT /* re-using the same name as in curl.h */
   317 
   318 #ifdef CURL_ISOCPP
   319 #define CINIT(name,type,num) CURLMOPT_ ## name = CURLOPTTYPE_ ## type + num
   320 #else
   321 /* The macro "##" is ISO C, we assume pre-ISO C doesn't support it. */
   322 #define LONG          CURLOPTTYPE_LONG
   323 #define OBJECTPOINT   CURLOPTTYPE_OBJECTPOINT
   324 #define FUNCTIONPOINT CURLOPTTYPE_FUNCTIONPOINT
   325 #define OFF_T         CURLOPTTYPE_OFF_T
   326 #define CINIT(name,type,number) CURLMOPT_/**/name = type + number
   327 #endif
   328 
   329 typedef enum {
   330   /* This is the socket callback function pointer */
   331   CINIT(SOCKETFUNCTION, FUNCTIONPOINT, 1),
   332 
   333   /* This is the argument passed to the socket callback */
   334   CINIT(SOCKETDATA, OBJECTPOINT, 2),
   335 
   336     /* set to 1 to enable pipelining for this multi handle */
   337   CINIT(PIPELINING, LONG, 3),
   338 
   339    /* This is the timer callback function pointer */
   340   CINIT(TIMERFUNCTION, FUNCTIONPOINT, 4),
   341 
   342   /* This is the argument passed to the timer callback */
   343   CINIT(TIMERDATA, OBJECTPOINT, 5),
   344 
   345   /* maximum number of entries in the connection cache */
   346   CINIT(MAXCONNECTS, LONG, 6),
   347 
   348   /* maximum number of (pipelining) connections to one host */
   349   CINIT(MAX_HOST_CONNECTIONS, LONG, 7),
   350 
   351   /* maximum number of requests in a pipeline */
   352   CINIT(MAX_PIPELINE_LENGTH, LONG, 8),
   353 
   354   /* a connection with a content-length longer than this
   355      will not be considered for pipelining */
   356   CINIT(CONTENT_LENGTH_PENALTY_SIZE, OFF_T, 9),
   357 
   358   /* a connection with a chunk length longer than this
   359      will not be considered for pipelining */
   360   CINIT(CHUNK_LENGTH_PENALTY_SIZE, OFF_T, 10),
   361 
   362   /* a list of site names(+port) that are blacklisted from
   363      pipelining */
   364   CINIT(PIPELINING_SITE_BL, OBJECTPOINT, 11),
   365 
   366   /* a list of server types that are blacklisted from
   367      pipelining */
   368   CINIT(PIPELINING_SERVER_BL, OBJECTPOINT, 12),
   369 
   370   /* maximum number of open connections in total */
   371   CINIT(MAX_TOTAL_CONNECTIONS, LONG, 13),
   372 
   373    /* This is the server push callback function pointer */
   374   CINIT(PUSHFUNCTION, FUNCTIONPOINT, 14),
   375 
   376   /* This is the argument passed to the server push callback */
   377   CINIT(PUSHDATA, OBJECTPOINT, 15),
   378 
   379   CURLMOPT_LASTENTRY /* the last unused */
   380 } CURLMoption;
   381 
   382 
   383 /*
   384  * Name:    curl_multi_setopt()
   385  *
   386  * Desc:    Sets options for the multi handle.
   387  *
   388  * Returns: CURLM error code.
   389  */
   390 CURL_EXTERN CURLMcode curl_multi_setopt(CURLM *multi_handle,
   391                                         CURLMoption option, ...);
   392 
   393 
   394 /*
   395  * Name:    curl_multi_assign()
   396  *
   397  * Desc:    This function sets an association in the multi handle between the
   398  *          given socket and a private pointer of the application. This is
   399  *          (only) useful for curl_multi_socket uses.
   400  *
   401  * Returns: CURLM error code.
   402  */
   403 CURL_EXTERN CURLMcode curl_multi_assign(CURLM *multi_handle,
   404                                         curl_socket_t sockfd, void *sockp);
   405 
   406 
   407 /*
   408  * Name: curl_push_callback
   409  *
   410  * Desc: This callback gets called when a new stream is being pushed by the
   411  *       server. It approves or denies the new stream.
   412  *
   413  * Returns: CURL_PUSH_OK or CURL_PUSH_DENY.
   414  */
   415 #define CURL_PUSH_OK   0
   416 #define CURL_PUSH_DENY 1
   417 
   418 struct curl_pushheaders;  /* forward declaration only */
   419 
   420 CURL_EXTERN char *curl_pushheader_bynum(struct curl_pushheaders *h,
   421                                         size_t num);
   422 CURL_EXTERN char *curl_pushheader_byname(struct curl_pushheaders *h,
   423                                          const char *name);
   424 
   425 typedef int (*curl_push_callback)(CURL *parent,
   426                                   CURL *easy,
   427                                   size_t num_headers,
   428                                   struct curl_pushheaders *headers,
   429                                   void *userp);
   430 
   431 #ifdef __cplusplus
   432 } /* end of extern "C" */
   433 #endif
   434 
   435 #endif