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