CURLMOPT_PUSHFUNCTION(3)

1CURLMOPT_PUSHFUNCTION(3)   curl_multi_setopt options  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       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

DESCRIPTION

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

CALLBACK DESCRIPTION

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 al‐
34       ter 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

CALLBACK RETURN VALUE

71       CURL_PUSH_OK (0)
72              The application has accepted the stream and it can now start re‐
73              ceiving  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       CURL_PUSH_ERROROUT (2)
81              Returning this will reject the pushed stream and return an error
82              back on the parent stream making it get closed  with  an  error.
83              (Added in curl 7.72.0)
84
85       *      All other return codes are reserved for future use.
86

DEFAULT

88       NULL, no callback
89

PROTOCOLS

91       HTTP(S) (HTTP/2 only)
92

EXAMPLE

94       /* only allow pushes for file names starting with "push-" */
95       int push_callback(CURL *parent,
96                         CURL *easy,
97                         size_t num_headers,
98                         struct curl_pushheaders *headers,
99                         void *userp)
100       {
101         char *headp;
102         int *transfers = (int *)userp;
103         FILE *out;
104         headp = curl_pushheader_byname(headers, ":path");
105         if(headp && !strncmp(headp, "/push-", 6)) {
106           fprintf(stderr, "The PATH is %s\n", headp);
107
108           /* save the push here */
109           out = fopen("pushed-stream", "wb");
110
111           /* write to this file */
112           curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
113
114           (*transfers)++; /* one more */
115
116           return CURL_PUSH_OK;
117         }
118         return CURL_PUSH_DENY;
119       }
120
121       curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
122       curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
123

AVAILABILITY

125       Added in 7.44.0
126

RETURN VALUE

128       Returns  CURLM_OK  if the option is supported, and CURLM_UNKNOWN_OPTION
129       if not.
130