.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PUSHFUNCTION 3 "December 04, 2023" "ibcurl 8.5.0" libcurl

.SH NAME
CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
.SH SYNOPSIS
.nf
#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);
.fi
.SH 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.
.SH CALLBACK DESCRIPTION
The callback gets its arguments like this:

\fIparent\fP 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.

\fIeasy\fP is a newly created handle that represents this upcoming transfer.

\fInum_headers\fP is the number of name+value pairs that was received and can
be accessed

\fIheaders\fP 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.

\fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP

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: \fIcurl_pushheader_byname(3)\fP and
\fIcurl_pushheader_bynum(3)\fP. 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 \fIcurl_easy_header(3)\fP,
introduced in later libcurl versions.
.SH CALLBACK RETURN VALUE
.IP "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.
.IP "CURL_PUSH_DENY (1)"
The callback denies the stream and no data reaches the application, the easy
handle is destroyed by libcurl.
.IP "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)
.IP *
All other return codes are reserved for future use.
.SH DEFAULT
NULL, no callback
.SH PROTOCOLS
HTTP(S) (HTTP/2 only)
.SH EXAMPLE
.nf
#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);
}
.fi
.SH AVAILABILITY
Added in 7.44.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PUSHDATA (3),
.BR CURLMOPT_PIPELINING (3),
.BR CURLOPT_PIPEWAIT (3),
.BR RFC 7540