CURLMOPT_PUSHFUNCTION(3)

1CURLMOPT_PUSHFUNCTION(3)            libcurl           CURLMOPT_PUSHFUNCTION(3)
2
3
4

NAME

6       CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       int curl_push_callback(CURL *parent,
12                              CURL *easy,
13                              size_t num_headers,
14                              struct curl_pushheaders *headers,
15                              void *clientp);
16
17       CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
18                                   curl_push_callback func);
19

DESCRIPTION

21       This  callback  gets called when a new HTTP/2 stream is being pushed by
22       the server (using the PUSH_PROMISE frame). If no push callback is  set,
23       all offered pushes will be denied automatically.
24

CALLBACK DESCRIPTION

26       The callback gets its arguments like this:
27
28       parent  is the handle of the stream on which this push arrives. The new
29       handle has been duplicated from the parent, meaning that it has  gotten
30       all  its  options  inherited. It is then up to the application to alter
31       any options if desired.
32
33       easy is a newly created handle that represents this upcoming transfer.
34
35       num_headers is the number of name+value pairs that was received and can
36       be accessed
37
38       headers  is  a  handle  used  to access push headers using the accessor
39       functions  described  below.  This  only  accesses  and  provides   the
40       PUSH_PROMISE  headers,  the normal response headers will be provided in
41       the header callback as usual.
42
43       clientp is the pointer set with CURLMOPT_PUSHDATA(3)
44
45       If the callback returns CURL_PUSH_OK, the 'easy' handle will  be  added
46       to the multi handle, the callback must not do that by itself.
47
48       The  callback  can  access PUSH_PROMISE headers with two accessor func‐
49       tions. These functions can only be used from within this  callback  and
50       they  can  only  access  the  PUSH_PROMISE headers: curl_pushheader_by‐
51       name(3) and curl_pushheader_bynum(3). The normal response headers  will
52       be  passed to the header callback for pushed streams just as for normal
53       streams.
54
55       The header fields can also be accessed with curl_easy_header(3), intro‐
56       duced in later libcurl versions.
57

CALLBACK RETURN VALUE

59       CURL_PUSH_OK (0)
60              The application has accepted the stream and it can now start re‐
61              ceiving data, the ownership of the CURL handle  has  been  taken
62              over by the application.
63
64       CURL_PUSH_DENY (1)
65              The  callback  denies the stream and no data for this will reach
66              the application, the easy handle will be destroyed by libcurl.
67
68       CURL_PUSH_ERROROUT (2)
69              Returning this will reject the pushed stream and return an error
70              back  on  the  parent stream making it get closed with an error.
71              (Added in 7.72.0)
72
73       *      All other return codes are reserved for future use.
74

DEFAULT

76       NULL, no callback
77

PROTOCOLS

79       HTTP(S) (HTTP/2 only)
80

EXAMPLE

82       /* only allow pushes for file names starting with "push-" */
83       int push_callback(CURL *parent,
84                         CURL *easy,
85                         size_t num_headers,
86                         struct curl_pushheaders *headers,
87                         void *clientp)
88       {
89         char *headp;
90         int *transfers = (int *)clientp;
91         FILE *out;
92         headp = curl_pushheader_byname(headers, ":path");
93         if(headp && !strncmp(headp, "/push-", 6)) {
94           fprintf(stderr, "The PATH is %s\n", headp);
95
96           /* save the push here */
97           out = fopen("pushed-stream", "wb");
98
99           /* write to this file */
100           curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
101
102           (*transfers)++; /* one more */
103
104           return CURL_PUSH_OK;
105         }
106         return CURL_PUSH_DENY;
107       }
108
109       curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
110       curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
111

AVAILABILITY

113       Added in 7.44.0
114

RETURN VALUE

116       Returns CURLM_OK if the option is supported,  and  CURLM_UNKNOWN_OPTION
117       if not.
118