xref: /aosp_15_r20/external/curl/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md (revision 6236dae45794135f37c4eb022389c904c8b0090d)
1*6236dae4SAndroid Build Coastguard Worker---
2*6236dae4SAndroid Build Coastguard Workerc: Copyright (C) Daniel Stenberg, <[email protected]>, et al.
3*6236dae4SAndroid Build Coastguard WorkerSPDX-License-Identifier: curl
4*6236dae4SAndroid Build Coastguard WorkerTitle: CURLMOPT_PUSHFUNCTION
5*6236dae4SAndroid Build Coastguard WorkerSection: 3
6*6236dae4SAndroid Build Coastguard WorkerSource: libcurl
7*6236dae4SAndroid Build Coastguard WorkerSee-also:
8*6236dae4SAndroid Build Coastguard Worker  - CURLMOPT_PIPELINING (3)
9*6236dae4SAndroid Build Coastguard Worker  - CURLMOPT_PUSHDATA (3)
10*6236dae4SAndroid Build Coastguard Worker  - CURLOPT_PIPEWAIT (3)
11*6236dae4SAndroid Build Coastguard Worker  - RFC 7540
12*6236dae4SAndroid Build Coastguard WorkerProtocol:
13*6236dae4SAndroid Build Coastguard Worker  - HTTP
14*6236dae4SAndroid Build Coastguard WorkerAdded-in: 7.44.0
15*6236dae4SAndroid Build Coastguard Worker---
16*6236dae4SAndroid Build Coastguard Worker
17*6236dae4SAndroid Build Coastguard Worker# NAME
18*6236dae4SAndroid Build Coastguard Worker
19*6236dae4SAndroid Build Coastguard WorkerCURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes
20*6236dae4SAndroid Build Coastguard Worker
21*6236dae4SAndroid Build Coastguard Worker# SYNOPSIS
22*6236dae4SAndroid Build Coastguard Worker
23*6236dae4SAndroid Build Coastguard Worker~~~c
24*6236dae4SAndroid Build Coastguard Worker#include <curl/curl.h>
25*6236dae4SAndroid Build Coastguard Worker
26*6236dae4SAndroid Build Coastguard Workerint curl_push_callback(CURL *parent,
27*6236dae4SAndroid Build Coastguard Worker                       CURL *easy,
28*6236dae4SAndroid Build Coastguard Worker                       size_t num_headers,
29*6236dae4SAndroid Build Coastguard Worker                       struct curl_pushheaders *headers,
30*6236dae4SAndroid Build Coastguard Worker                       void *clientp);
31*6236dae4SAndroid Build Coastguard Worker
32*6236dae4SAndroid Build Coastguard WorkerCURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
33*6236dae4SAndroid Build Coastguard Worker                            curl_push_callback func);
34*6236dae4SAndroid Build Coastguard Worker~~~
35*6236dae4SAndroid Build Coastguard Worker
36*6236dae4SAndroid Build Coastguard Worker# DESCRIPTION
37*6236dae4SAndroid Build Coastguard Worker
38*6236dae4SAndroid Build Coastguard WorkerThis callback gets called when a new HTTP/2 stream is being pushed by the
39*6236dae4SAndroid Build Coastguard Workerserver (using the PUSH_PROMISE frame). If no push callback is set, all offered
40*6236dae4SAndroid Build Coastguard Workerpushes are denied automatically.
41*6236dae4SAndroid Build Coastguard Worker
42*6236dae4SAndroid Build Coastguard Worker# CALLBACK DESCRIPTION
43*6236dae4SAndroid Build Coastguard Worker
44*6236dae4SAndroid Build Coastguard WorkerThe callback gets its arguments like this:
45*6236dae4SAndroid Build Coastguard Worker
46*6236dae4SAndroid Build Coastguard Worker*parent* is the handle of the stream on which this push arrives. The new
47*6236dae4SAndroid Build Coastguard Workerhandle has been duplicated from the parent, meaning that it has gotten all its
48*6236dae4SAndroid Build Coastguard Workeroptions inherited. It is then up to the application to alter any options if
49*6236dae4SAndroid Build Coastguard Workerdesired.
50*6236dae4SAndroid Build Coastguard Worker
51*6236dae4SAndroid Build Coastguard Worker*easy* is a newly created handle that represents this upcoming transfer.
52*6236dae4SAndroid Build Coastguard Worker
53*6236dae4SAndroid Build Coastguard Worker*num_headers* is the number of name+value pairs that was received and can
54*6236dae4SAndroid Build Coastguard Workerbe accessed
55*6236dae4SAndroid Build Coastguard Worker
56*6236dae4SAndroid Build Coastguard Worker*headers* is a handle used to access push headers using the accessor
57*6236dae4SAndroid Build Coastguard Workerfunctions described below. This only accesses and provides the PUSH_PROMISE
58*6236dae4SAndroid Build Coastguard Workerheaders, the normal response headers are provided in the header callback as
59*6236dae4SAndroid Build Coastguard Workerusual.
60*6236dae4SAndroid Build Coastguard Worker
61*6236dae4SAndroid Build Coastguard Worker*clientp* is the pointer set with CURLMOPT_PUSHDATA(3)
62*6236dae4SAndroid Build Coastguard Worker
63*6236dae4SAndroid Build Coastguard WorkerIf the callback returns CURL_PUSH_OK, the new easy handle is added to the
64*6236dae4SAndroid Build Coastguard Workermulti handle, the callback must not do that by itself.
65*6236dae4SAndroid Build Coastguard Worker
66*6236dae4SAndroid Build Coastguard WorkerThe callback can access PUSH_PROMISE headers with two accessor
67*6236dae4SAndroid Build Coastguard Workerfunctions. These functions can only be used from within this callback and they
68*6236dae4SAndroid Build Coastguard Workercan only access the PUSH_PROMISE headers: curl_pushheader_byname(3) and
69*6236dae4SAndroid Build Coastguard Workercurl_pushheader_bynum(3). The normal response headers are passed to the
70*6236dae4SAndroid Build Coastguard Workerheader callback for pushed streams just as for normal streams.
71*6236dae4SAndroid Build Coastguard Worker
72*6236dae4SAndroid Build Coastguard WorkerThe header fields can also be accessed with curl_easy_header(3),
73*6236dae4SAndroid Build Coastguard Workerintroduced in later libcurl versions.
74*6236dae4SAndroid Build Coastguard Worker
75*6236dae4SAndroid Build Coastguard Worker# CALLBACK RETURN VALUE
76*6236dae4SAndroid Build Coastguard Worker
77*6236dae4SAndroid Build Coastguard Worker## CURL_PUSH_OK (0)
78*6236dae4SAndroid Build Coastguard Worker
79*6236dae4SAndroid Build Coastguard WorkerThe application has accepted the stream and it can now start receiving data,
80*6236dae4SAndroid Build Coastguard Workerthe ownership of the CURL handle has been taken over by the application.
81*6236dae4SAndroid Build Coastguard Worker
82*6236dae4SAndroid Build Coastguard Worker## CURL_PUSH_DENY (1)
83*6236dae4SAndroid Build Coastguard Worker
84*6236dae4SAndroid Build Coastguard WorkerThe callback denies the stream and no data reaches the application, the easy
85*6236dae4SAndroid Build Coastguard Workerhandle is destroyed by libcurl.
86*6236dae4SAndroid Build Coastguard Worker
87*6236dae4SAndroid Build Coastguard Worker## CURL_PUSH_ERROROUT (2)
88*6236dae4SAndroid Build Coastguard Worker
89*6236dae4SAndroid Build Coastguard WorkerReturning this code rejects the pushed stream and returns an error back on the
90*6236dae4SAndroid Build Coastguard Workerparent stream making it get closed with an error. (Added in 7.72.0)
91*6236dae4SAndroid Build Coastguard Worker
92*6236dae4SAndroid Build Coastguard Worker## *
93*6236dae4SAndroid Build Coastguard Worker
94*6236dae4SAndroid Build Coastguard WorkerAll other return codes are reserved for future use.
95*6236dae4SAndroid Build Coastguard Worker
96*6236dae4SAndroid Build Coastguard Worker# DEFAULT
97*6236dae4SAndroid Build Coastguard Worker
98*6236dae4SAndroid Build Coastguard WorkerNULL, no callback
99*6236dae4SAndroid Build Coastguard Worker
100*6236dae4SAndroid Build Coastguard Worker# %PROTOCOLS%
101*6236dae4SAndroid Build Coastguard Worker
102*6236dae4SAndroid Build Coastguard Worker# EXAMPLE
103*6236dae4SAndroid Build Coastguard Worker
104*6236dae4SAndroid Build Coastguard Worker~~~c
105*6236dae4SAndroid Build Coastguard Worker#include <string.h>
106*6236dae4SAndroid Build Coastguard Worker
107*6236dae4SAndroid Build Coastguard Worker/* only allow pushes for filenames starting with "push-" */
108*6236dae4SAndroid Build Coastguard Workerint push_callback(CURL *parent,
109*6236dae4SAndroid Build Coastguard Worker                  CURL *easy,
110*6236dae4SAndroid Build Coastguard Worker                  size_t num_headers,
111*6236dae4SAndroid Build Coastguard Worker                  struct curl_pushheaders *headers,
112*6236dae4SAndroid Build Coastguard Worker                  void *clientp)
113*6236dae4SAndroid Build Coastguard Worker{
114*6236dae4SAndroid Build Coastguard Worker  char *headp;
115*6236dae4SAndroid Build Coastguard Worker  int *transfers = (int *)clientp;
116*6236dae4SAndroid Build Coastguard Worker  FILE *out;
117*6236dae4SAndroid Build Coastguard Worker  headp = curl_pushheader_byname(headers, ":path");
118*6236dae4SAndroid Build Coastguard Worker  if(headp && !strncmp(headp, "/push-", 6)) {
119*6236dae4SAndroid Build Coastguard Worker    fprintf(stderr, "The PATH is %s\n", headp);
120*6236dae4SAndroid Build Coastguard Worker
121*6236dae4SAndroid Build Coastguard Worker    /* save the push here */
122*6236dae4SAndroid Build Coastguard Worker    out = fopen("pushed-stream", "wb");
123*6236dae4SAndroid Build Coastguard Worker
124*6236dae4SAndroid Build Coastguard Worker    /* write to this file */
125*6236dae4SAndroid Build Coastguard Worker    curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
126*6236dae4SAndroid Build Coastguard Worker
127*6236dae4SAndroid Build Coastguard Worker    (*transfers)++; /* one more */
128*6236dae4SAndroid Build Coastguard Worker
129*6236dae4SAndroid Build Coastguard Worker    return CURL_PUSH_OK;
130*6236dae4SAndroid Build Coastguard Worker  }
131*6236dae4SAndroid Build Coastguard Worker  return CURL_PUSH_DENY;
132*6236dae4SAndroid Build Coastguard Worker}
133*6236dae4SAndroid Build Coastguard Worker
134*6236dae4SAndroid Build Coastguard Workerint main(void)
135*6236dae4SAndroid Build Coastguard Worker{
136*6236dae4SAndroid Build Coastguard Worker  int counter;
137*6236dae4SAndroid Build Coastguard Worker  CURLM *multi = curl_multi_init();
138*6236dae4SAndroid Build Coastguard Worker  curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
139*6236dae4SAndroid Build Coastguard Worker  curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
140*6236dae4SAndroid Build Coastguard Worker}
141*6236dae4SAndroid Build Coastguard Worker~~~
142*6236dae4SAndroid Build Coastguard Worker
143*6236dae4SAndroid Build Coastguard Worker# %AVAILABILITY%
144*6236dae4SAndroid Build Coastguard Worker
145*6236dae4SAndroid Build Coastguard Worker# RETURN VALUE
146*6236dae4SAndroid Build Coastguard Worker
147*6236dae4SAndroid Build Coastguard WorkerReturns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
148