NAME

       CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes

SYNOPSIS

       #include <curl/curl.h>

       int curl_push_callback(CURL *parent,
                              CURL *easy,
                              size_t num_headers,
                              struct curl_pushheaders *headers,
                              void *clientp);

       CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
                                   curl_push_callback func);

DESCRIPTION

       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 are denied automatically.

CALLBACK DESCRIPTION

       The callback gets its arguments like this:

       parent is the handle of the stream on which this push arrives. The new handle has  been  duplicated  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.

       easy is a newly created handle that represents this upcoming transfer.

       num_headers is the number of name+value pairs that was received and can be accessed

       headers 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 are provided in the header
       callback as usual.

       clientp is the pointer set with CURLMOPT_PUSHDATA(3)

       If the callback returns CURL_PUSH_OK, the new easy handle is added to the multi handle, the callback must
       not do that by itself.

       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:
       curl_pushheader_byname(3) and curl_pushheader_bynum(3). The normal response headers  are  passed  to  the
       header callback for pushed streams just as for normal streams.

       The header fields can also be accessed with curl_easy_header(3), introduced in later libcurl versions.

CALLBACK RETURN VALUE

       CURL_PUSH_OK (0)
              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.

       CURL_PUSH_DENY (1)
              The callback denies the stream and no data reaches the application, the easy handle  is  destroyed
              by libcurl.

       CURL_PUSH_ERROROUT (2)
              Returning  this  code  rejects  the  pushed  stream and returns an error back on the parent stream
              making it get closed with an error. (Added in 7.72.0)

       *      All other return codes are reserved for future use.

DEFAULT

       NULL, no callback

PROTOCOLS

       HTTP(S) (HTTP/2 only)

EXAMPLE

       #include <string.h>

       /* only allow pushes for file names starting with "push-" */
       int push_callback(CURL *parent,
                         CURL *easy,
                         size_t num_headers,
                         struct curl_pushheaders *headers,
                         void *clientp)
       {
         char *headp;
         int *transfers = (int *)clientp;
         FILE *out;
         headp = curl_pushheader_byname(headers, ":path");
         if(headp && !strncmp(headp, "/push-", 6)) {
           fprintf(stderr, "The PATH is %s\n", headp);

           /* save the push here */
           out = fopen("pushed-stream", "wb");

           /* write to this file */
           curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);

           (*transfers)++; /* one more */

           return CURL_PUSH_OK;
         }
         return CURL_PUSH_DENY;
       }

       int main(void)
       {
         int counter;
         CURLM *multi = curl_multi_init();
         curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
         curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
       }

AVAILABILITY

       Added in 7.44.0

RETURN VALUE

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

SEE ALSO

       CURLMOPT_PUSHDATA(3), CURLMOPT_PIPELINING(3), CURLOPT_PIPEWAIT(3), RFC7540

ibcurl 8.5.0                                    December 04, 2023                       CURLMOPT_PUSHFUNCTION(3)