docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2  "http://www.w3.org/TR/html4/loose.dtd">
   3 <html><head>
   4 <title>CURLMOPT_PUSHFUNCTION man page</title>
   5 <meta name="generator" content="roffit">
   6 <STYLE type="text/css">
   7 pre {
   8   overflow: auto;
   9   margin: 0;
  10 }
  11
  12 P.level0, pre.level0 {
  13  padding-left: 2em;
  14 }
  15
  16 P.level1, pre.level1 {
  17  padding-left: 4em;
  18 }
  19
  20 P.level2, pre.level2 {
  21  padding-left: 6em;
  22 }
  23
  24 span.emphasis {
  25  font-style: italic;
  26 }
  27
  28 span.bold {
  29  font-weight: bold;
  30 }
  31
  32 span.manpage {
  33  font-weight: bold;
  34 }
  35
  36 h2.nroffsh {
  37  background-color: #e0e0e0;
  38 }
  39
  40 span.nroffip {
  41  font-weight: bold;
  42  font-size: 120%;
  43  font-family: monospace;
  44 }
  45
  46 p.roffit {
  47  text-align: center;
  48  font-size: 80%;
  49 }
  50 </STYLE>
  51 </head><body>
  52
  53 <p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2>
  54 <p class="level0">CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2>
  55 <p class="level0"><pre class="level0">
  56 &#35;include &lt;curl/curl.h&gt;
  57 &nbsp;
  58 char *curl_pushheader_bynum(push_headers, int num);
  59 char *curl_pushheader_byname(push_headers, const char *name);
  60 &nbsp;
  61 int curl_push_callback(CURL *parent,
  62 &nbsp;                      CURL *easy,
  63 &nbsp;                      size_t num_headers,
  64 &nbsp;                      struct curl_pushheaders *headers,
  65 &nbsp;                      void *userp);
  66 &nbsp;
  67 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
  68 &nbsp;                           curl_push_callback func);
  69 </pre>
  70
  71 <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2>
  72 <p class="level0">This callback gets called when a new HTTP/2 stream is being pushed by the server (using the PUSH_PROMISE frame). If no push callback is set, all offered pushes will be denied automatically. <a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK DESCRIPTION</h2>
  73 <p class="level0">The callback gets its arguments like this:
  74 <p class="level0"><span Class="emphasis">parent</span> is the handle of the stream on which this push arrives. The new handle has been duphandle()d from the parent, meaning that it has gotten all its options inherited. It is then up to the application to alter any options if desired.
  75 <p class="level0"><span Class="emphasis">easy</span> is a newly created handle that represents this upcoming transfer.
  76 <p class="level0"><span Class="emphasis">num_headers</span> is the number of name+value pairs that was received and can be accessed
  77 <p class="level0"><span Class="emphasis">headers</span> is a handle used to access push headers using the accessor functions described below. This only accesses and provides the PUSH_PROMISE headers, the normal response headers will be provided in the header callback as usual.
  78 <p class="level0"><span Class="emphasis">userp</span> is the pointer set with <a Class="emphasis" href="./CURLMOPT_PUSHDATA.html">CURLMOPT_PUSHDATA</a>
  79 <p class="level0">If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the multi handle, the callback must not do that by itself.
  80 <p class="level0">The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they can only access the PUSH_PROMISE headers. The normal response headers will be pased to the header callback for pushed streams just as for normal streams.
  81 <p class="level0"><a name="curlpushheaderbynum"></a><span class="nroffip">curl_pushheader_bynum</span>
  82 <p class="level1">Returns the header at index 'num' (or NULL). The returned pointer points to a "name:value" string that will be freed when this callback returns.
  83 <p class="level0"><a name="curlpushheaderbyname"></a><span class="nroffip">curl_pushheader_byname</span>
  84 <p class="level1">Returns the value for the given header name (or NULL). This is a shortcut so that the application doesn't have to loop through all headers to find the one it is interested in. The data pointed will be freed when this callback returns. <a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK RETURN VALUE</h2>
  85 <p class="level0">
  86 <p class="level0"><a name="CURLPUSHOK"></a><span class="nroffip">CURL_PUSH_OK (0)</span>
  87 <p class="level1">The application has accepted the stream and it can now start receiving data, the ownership of the CURL handle has been taken over by the application.
  88 <p class="level0"><a name="CURLPUSHDENY"></a><span class="nroffip">CURL_PUSH_DENY (1)</span>
  89 <p class="level1">The callback denies the stream and no data for this will reach the application, the easy handle will be destroyed by libcurl.
  90 <p class="level0"><a name=""></a><span class="nroffip">*</span>
  91 <p class="level1">All other return codes are reserved for future use. <a name="DEFAULT"></a><h2 class="nroffsh">DEFAULT</h2>
  92 <p class="level0">NULL, no callback <a name="PROTOCOLS"></a><h2 class="nroffsh">PROTOCOLS</h2>
  93 <p class="level0">HTTP(S) (HTTP/2 only) <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2>
  94 <p class="level0"><pre class="level0">
  95 /* only allow pushes for file names starting with "push-" */
  96 int push_callback(CURL *parent,
  97 &nbsp;                 CURL *easy,
  98 &nbsp;                 size_t num_headers,
  99 &nbsp;                 struct curl_pushheaders *headers,
 100 &nbsp;                 void *userp)
 101 {
 102 &nbsp; char *headp;
 103 &nbsp; int *transfers = (int *)userp;
 104 &nbsp; FILE *out;
 105 &nbsp; headp = curl_pushheader_byname(headers, ":path");
 106 &nbsp; if(headp && !strncmp(headp, "/push-", 6)) {
 107 &nbsp;   fprintf(stderr, "The PATH is %sn", headp);
 108 &nbsp;
 109 &nbsp;   /* save the push here */
 110 &nbsp;   out = fopen("pushed-stream", "wb");
 111 &nbsp;
 112 &nbsp;   /* write to this file */
 113 &nbsp;   curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
 114 &nbsp;
 115 &nbsp;   (*transfers)++; /* one more */
 116 &nbsp;
 117 &nbsp;   return CURL_PUSH_OK;
 118 &nbsp; }
 119 &nbsp; return CURL_PUSH_DENY;
 120 }
 121 &nbsp;
 122 curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
 123 curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
 124 </pre>
 125
 126 <p class="level0"><a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2>
 127 <p class="level0">Added in 7.44.0 <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2>
 128 <p class="level0">Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2>
 129 <p class="level0"><a Class="manpage" href="./CURLMOPT_PUSHDATA.html">CURLMOPT_PUSHDATA</a>, <a Class="manpage" href="./CURLMOPT_PIPELINING.html">CURLMOPT_PIPELINING</a>, <a Class="manpage" href="./CURLOPT_PIPEWAIT.html">CURLOPT_PIPEWAIT</a>, <a class="manpage" href="#"> </a> <span Class="manpage"><a href="http://www.ietf.org/rfc/rfc7540.txt">RFC 7540</a></span> <p class="roffit">
 130  This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>.
 131 </body></html>