docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLMOPT_PUSHFUNCTION 3 "February 03, 2016" "libcurl 7.59.0" "curl_multi_setopt options"
  24
  25 .SH NAME
  26 CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
  27 .SH SYNOPSIS
  28 .nf
  29 #include <curl/curl.h>
  30
  31 char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num);
  32 char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name);
  33
  34 int curl_push_callback(CURL *parent,
  35                        CURL *easy,
  36                        size_t num_headers,
  37                        struct curl_pushheaders *headers,
  38                        void *userp);
  39
  40 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
  41                             curl_push_callback func);
  42 .fi
  43 .SH DESCRIPTION
  44 This callback gets called when a new HTTP/2 stream is being pushed by the
  45 server (using the PUSH_PROMISE frame). If no push callback is set, all offered
  46 pushes will be denied automatically.
  47 .SH CALLBACK DESCRIPTION
  48 The callback gets its arguments like this:
  49
  50 \fIparent\fP is the handle of the stream on which this push arrives. The new
  51 handle has been duphandle()d from the parent, meaning that it has gotten all
  52 its options inherited. It is then up to the application to alter any options
  53 if desired.
  54
  55 \fIeasy\fP is a newly created handle that represents this upcoming transfer.
  56
  57 \fInum_headers\fP is the number of name+value pairs that was received and can
  58 be accessed
  59
  60 \fIheaders\fP is a handle used to access push headers using the accessor
  61 functions described below. This only accesses and provides the PUSH_PROMISE
  62 headers, the normal response headers will be provided in the header callback
  63 as usual.
  64
  65 \fIuserp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP
  66
  67 If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the
  68 multi handle, the callback must not do that by itself.
  69
  70 The callback can access PUSH_PROMISE headers with two accessor
  71 functions. These functions can only be used from within this callback and they
  72 can only access the PUSH_PROMISE headers. The normal response headers will be
  73 passed to the header callback for pushed streams just as for normal streams.
  74 .IP curl_pushheader_bynum
  75 Returns the header at index 'num' (or NULL). The returned pointer points to a
  76 "name:value" string that will be freed when this callback returns.
  77 .IP curl_pushheader_byname
  78 Returns the value for the given header name (or NULL). This is a shortcut so
  79 that the application doesn't have to loop through all headers to find the one
  80 it is interested in. The data pointed will be freed when this callback
  81 returns. If more than one header field use the same name, this returns only
  82 the first one.
  83 .SH CALLBACK RETURN VALUE
  84 .IP "CURL_PUSH_OK (0)"
  85 The application has accepted the stream and it can now start receiving data,
  86 the ownership of the CURL handle has been taken over by the application.
  87 .IP "CURL_PUSH_DENY (1)"
  88 The callback denies the stream and no data for this will reach the
  89 application, the easy handle will be destroyed by libcurl.
  90 .IP *
  91 All other return codes are reserved for future use.
  92 .SH DEFAULT
  93 NULL, no callback
  94 .SH PROTOCOLS
  95 HTTP(S) (HTTP/2 only)
  96 .SH EXAMPLE
  97 .nf
  98 /* only allow pushes for file names starting with "push-" */
  99 int push_callback(CURL *parent,
 100                   CURL *easy,
 101                   size_t num_headers,
 102                   struct curl_pushheaders *headers,
 103                   void *userp)
 104 {
 105   char *headp;
 106   int *transfers = (int *)userp;
 107   FILE *out;
 108   headp = curl_pushheader_byname(headers, ":path");
 109   if(headp && !strncmp(headp, "/push-", 6)) {
 110     fprintf(stderr, "The PATH is %s\\n", headp);
 111
 112     /* save the push here */
 113     out = fopen("pushed-stream", "wb");
 114
 115     /* write to this file */
 116     curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
 117
 118     (*transfers)++; /* one more */
 119
 120     return CURL_PUSH_OK;
 121   }
 122   return CURL_PUSH_DENY;
 123 }
 124
 125 curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
 126 curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
 127 .fi
 128 .SH AVAILABILITY
 129 Added in 7.44.0
 130 .SH RETURN VALUE
 131 Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
 132 .SH "SEE ALSO"
 133 .BR CURLMOPT_PUSHDATA "(3), " CURLMOPT_PIPELINING "(3), " CURLOPT_PIPEWAIT "(3), "
 134 .BR RFC 7540