1CURLMOPT_PUSHFUNCTION(3) curl_multi_setopt options CURLMOPT_PUSHFUNCTION(3)
2
3
4
6 CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes
7
9 #include <curl/curl.h>
10
11 char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num);
12 char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name);
13
14 int curl_push_callback(CURL *parent,
15 CURL *easy,
16 size_t num_headers,
17 struct curl_pushheaders *headers,
18 void *userp);
19
20 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
21 curl_push_callback func);
22
24 This callback gets called when a new HTTP/2 stream is being pushed by
25 the server (using the PUSH_PROMISE frame). If no push callback is set,
26 all offered pushes will be denied automatically.
27
29 The callback gets its arguments like this:
30
31 parent is the handle of the stream on which this push arrives. The new
32 handle has been duphandle()d from the parent, meaning that it has got‐
33 ten all its options inherited. It is then up to the application to
34 alter any options if desired.
35
36 easy is a newly created handle that represents this upcoming transfer.
37
38 num_headers is the number of name+value pairs that was received and can
39 be accessed
40
41 headers is a handle used to access push headers using the accessor
42 functions described below. This only accesses and provides the
43 PUSH_PROMISE headers, the normal response headers will be provided in
44 the header callback as usual.
45
46 userp is the pointer set with CURLMOPT_PUSHDATA(3)
47
48 If the callback returns CURL_PUSH_OK, the 'easy' handle will be added
49 to the multi handle, the callback must not do that by itself.
50
51 The callback can access PUSH_PROMISE headers with two accessor func‐
52 tions. These functions can only be used from within this callback and
53 they can only access the PUSH_PROMISE headers. The normal response
54 headers will be passed to the header callback for pushed streams just
55 as for normal streams.
56
57 curl_pushheader_bynum
58 Returns the header at index 'num' (or NULL). The returned
59 pointer points to a "name:value" string that will be freed when
60 this callback returns.
61
62 curl_pushheader_byname
63 Returns the value for the given header name (or NULL). This is a
64 shortcut so that the application doesn't have to loop through
65 all headers to find the one it is interested in. The data
66 pointed will be freed when this callback returns. If more than
67 one header field use the same name, this returns only the first
68 one.
69
71 CURL_PUSH_OK (0)
72 The application has accepted the stream and it can now start
73 receiving data, the ownership of the CURL handle has been taken
74 over by the application.
75
76 CURL_PUSH_DENY (1)
77 The callback denies the stream and no data for this will reach
78 the application, the easy handle will be destroyed by libcurl.
79
80 * All other return codes are reserved for future use.
81
83 NULL, no callback
84
86 HTTP(S) (HTTP/2 only)
87
89 /* only allow pushes for file names starting with "push-" */
90 int push_callback(CURL *parent,
91 CURL *easy,
92 size_t num_headers,
93 struct curl_pushheaders *headers,
94 void *userp)
95 {
96 char *headp;
97 int *transfers = (int *)userp;
98 FILE *out;
99 headp = curl_pushheader_byname(headers, ":path");
100 if(headp && !strncmp(headp, "/push-", 6)) {
101 fprintf(stderr, "The PATH is %s\n", headp);
102
103 /* save the push here */
104 out = fopen("pushed-stream", "wb");
105
106 /* write to this file */
107 curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
108
109 (*transfers)++; /* one more */
110
111 return CURL_PUSH_OK;
112 }
113 return CURL_PUSH_DENY;
114 }
115
116 curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
117 curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
118
120 Added in 7.44.0
121
123 Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION
124 if not.
125
127 CURLMOPT_PUSHDATA(3), CURLMOPT_PIPELINING(3), CURLOPT_PIPEWAIT(3),
128 RFC7540
129
130
131
132libcurl 7.61.1 February 03, 2016 CURLMOPT_PUSHFUNCTION(3)