1 .\" **************************************************************************
3 .\" * Project ___| | | | _ \| |
4 .\" * / __| | | | |_) | |
5 .\" * | (__| |_| | _ <| |___
6 .\" * \___|\___/|_| \_\_____|
8 .\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
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 http://curl.haxx.se/docs/copyright.html.
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.
18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19 .\" * KIND, either express or implied.
21 .\" **************************************************************************
23 .TH CURLMOPT_PUSHFUNCTION 3 "1 Jun 2015" "libcurl 7.44.0" "curl_multi_setopt options"
25 CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
28 #include <curl/curl.h>
30 char *curl_pushheader_bynum(push_headers, int num);
31 char *curl_pushheader_byname(push_headers, const char *name);
33 int curl_push_callback(CURL *parent,
36 struct curl_pushheaders *headers,
39 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
40 curl_push_callback func);
43 This callback gets called when a new HTTP/2 stream is being pushed by the
44 server (using the PUSH_PROMISE frame). If no push callback is set, all offered
45 pushes will be denied automatically.
46 .SH CALLBACK DESCRIPTION
47 The callback gets its arguments like this:
49 \fIparent\fP is the handle of the stream on which this push arrives. The new
50 handle has been duphandle()d from the parent, meaning that it has gotten all
51 its options inherited. It is then up to the application to alter any options
54 \fIeasy\fP is a newly created handle that represents this upcoming transfer.
56 \fInum_headers\fP is the number of name+value pairs that was received and can
59 \fIheaders\fP is a handle used to access push headers using the accessor
60 functions described below. This only accesses and provides the PUSH_PROMISE
61 headers, the normal response headers will be provided in the header callback
64 \fIuserp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP
66 If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the
67 multi handle, the callback must not do that by itself.
69 The callback can access PUSH_PROMISE headers with two accessor
70 functions. These functions can only be used from within this callback and they
71 can only access the PUSH_PROMISE headers. The normal response headers will be
72 pased to the header callback for pushed streams just as for normal streams.
73 .IP curl_pushheader_bynum
74 Returns the header at index 'num' (or NULL). The returned pointer points to a
75 "name:value" string that will be freed when this callback returns.
76 .IP curl_pushheader_byname
77 Returns the value for the given header name (or NULL). This is a shortcut so
78 that the application doesn't have to loop through all headers to find the one
79 it is interested in. The data pointed will be freed when this callback
81 .SH CALLBACK RETURN VALUE
82 .IP "CURL_PUSH_OK (0)"
83 The application has accepted the stream and it can now start receiving data,
84 the ownership of the CURL handle has been taken over by the application.
85 .IP "CURL_PUSH_DENY (1)"
86 The callback denies the stream and no data for this will reach the
87 application, the easy handle will be destroyed by libcurl.
89 All other return codes are reserved for future use.
96 /* only allow pushes for file names starting with "push-" */
97 int push_callback(CURL *parent,
100 struct curl_pushheaders *headers,
104 int *transfers = (int *)userp;
106 headp = curl_pushheader_byname(headers, ":path");
107 if(headp && !strncmp(headp, "/push-", 6)) {
108 fprintf(stderr, "The PATH is %s\n", headp);
110 /* save the push here */
111 out = fopen("pushed-stream", "wb");
113 /* write to this file */
114 curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
116 (*transfers)++; /* one more */
120 return CURL_PUSH_DENY;
123 curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
124 curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
129 Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
131 .BR CURLMOPT_PUSHDATA "(3), " CURLMOPT_PIPELINING "(3), " CURLOPT_PIPEWAIT "(3), "