http2: initial HTTP/2 server push types/docs

docs/libcurl/opts/CURLMOPT_PUSHDATA.3

@@ -0,0 +1,49 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2015, 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 http://curl.haxx.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLMOPT_PUSHDATA 3 "1 Jun 2015" "libcurl 7.44.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_PUSHDATA \- pointer to pass to push callback
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer);
+.fi
+.SH DESCRIPTION
+Set \fIpointer\fP to pass as the last argument to the
+\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer will not be touched or
+used by libcurl itself, only passed on to the callback function.
+.SH DEFAULT
+NULL
+.SH PROTOCOLS
+HTTP(S)
+.SH EXAMPLE
+TODO
+.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_PUSHFUNCTION "(3), " CURLMOPT_PIPELINING "(3), "
+.BR CURLOPT_PIPEWAIT "(3), "
+.BR RFC 7540

docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3

@@ -0,0 +1,108 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2015, 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 http://curl.haxx.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLMOPT_PUSHFUNCTION 3 "1 Jun 2015" "libcurl 7.44.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_PUSHFUNCTION \- approve or deny server pushes
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+struct curl_headerpair {
+   unsigned char *name;   /* zero terminated name */
+   size_t namelen;        /* length of 'name' */
+   unsigned char *value;  /* zero terminated name */
+   size_t valuelen;       /* length of 'value' */
+};
+
+struct curl_headerpair *curl_pushheader_bynum(push_headers, int num);
+struct curl_headerpair *curl_pushheader_byname(push_headers, char *name);
+
+int curl_push_callback(CURL *parent,
+                       CURL *easy,
+                       int num_headers,
+                       struct curl_pushheaders *headers,
+                       void *userp);
+
+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 will be denied automatically.
+.SH CALLBACK DESCRIPTION
+The callback gets its arguments like this:
+
+\fIeasy\fP is a newly created handle that represents this new transfer.
+
+\fIparent\fP is the handle of the stream on which this push arrives. The new
+handle has been duphandle()d 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.
+
+\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 will be provided in the header callback
+as usual.
+
+\fIuserp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP
+
+If the callback returns CURL_PUSH_OK, the 'easy' handle will be 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. The normal response headers will be
+pased to the header callback for pushed streams just as for normal streams.
+.IP curl_pushheader_bynum
+Returns the header pair at index 'num' (or NULL). The returned pointer points
+to a struct that will be freed when this callback returns.
+.IP curl_pushheader_byname
+Returns the header pair for the given header name (or NULL). This is a
+shortcut so that the application doesn't have to loop through all headers to
+find the one it is interested in.
+.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 for this will reach the
+application, the easy handle will be destroyed by libcurl.
+.IP *
+All other return codes are reserved for future use.
+.SH DEFAULT
+NULL, no callback
+.SH PROTOCOLS
+HTTP(S) (HTTP/2 only)
+.SH EXAMPLE
+TODO
+.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), " CURLMOPT_PIPELINING "(3), " CURLOPT_PIPEWAIT "(3), "
+.BR RFC 7540

docs/libcurl/opts/Makefile.am

@@ -114,7 +114,8 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3		\
  CURLMOPT_SOCKETDATA.3 CURLMOPT_SOCKETFUNCTION.3 CURLMOPT_TIMERDATA.3	\
  CURLMOPT_TIMERFUNCTION.3 CURLOPT_UNIX_SOCKET_PATH.3			\
  CURLOPT_PATH_AS_IS.3 CURLOPT_PROXY_SERVICE_NAME.3			\
- CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3
+ CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3 CURLMOPT_PUSHDATA.3		\
+ CURLMOPT_PUSHFUNCTION.3
 
 HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html	\
  CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html				\
@@ -222,7 +223,8 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html	\
  CURLMOPT_TIMERDATA.html CURLMOPT_TIMERFUNCTION.html			\
  CURLOPT_UNIX_SOCKET_PATH.html CURLOPT_PATH_AS_IS.html			\
  CURLOPT_PROXY_SERVICE_NAME.html CURLOPT_SERVICE_NAME.html		\
- CURLOPT_PIPEWAIT.html
+ CURLOPT_PIPEWAIT.html CURLMOPT_PUSHDATA.html				\
+ CURLMOPT_PUSHFUNCTION.html
 
 PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf	\
  CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf	\
@@ -328,7 +330,7 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf	\
  CURLMOPT_TIMERDATA.pdf CURLMOPT_TIMERFUNCTION.pdf			\
  CURLOPT_UNIX_SOCKET_PATH.pdf CURLOPT_PATH_AS_IS.pdf			\
  CURLOPT_PROXY_SERVICE_NAME.pdf CURLOPT_SERVICE_NAME.pdf		\
- CURLOPT_PIPEWAIT.pdf
+ CURLOPT_PIPEWAIT.pdf CURLMOPT_PUSHDATA.pdf CURLMOPT_PUSHFUNCTION.pdf
 
 CLEANFILES = $(HTMLPAGES) $(PDFPAGES)
 

include/curl/multi.h

@@ -283,6 +283,32 @@ typedef int (*curl_multi_timer_callback)(CURLM *multi,    /* multi handle */
                                          void *userp);    /* private callback
                                                              pointer */
 
+/*
+ * Name: curl_push_callback
+ *
+ * Desc: This callback gets called when a new stream is being pushed by the
+ *       server. It approves or denies the new stream.
+ *
+ * Returns: CURL_PUSH_OK or CURL_PUSH_DENY.
+ */
+#define CURL_PUSH_OK   0
+#define CURL_PUSH_DENY 1
+
+struct curl_headerpair {
+   unsigned char *name;   /* zero terminated name */
+   size_t namelen;        /* length of 'name' */
+   unsigned char *value;  /* zero terminated name */
+   size_t valuelen;       /* length of 'value' */
+};
+
+struct curl_pushheaders;  /* forward declaration only */
+
+typedef int (*curl_push_callback)(CURL *parent,
+                                  CURL *easy,
+                                  int num_headers,
+                                  struct curl_pushheaders *headers,
+                                  void *userp);
+
 CURL_EXTERN CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t s,
                                         int *running_handles);
 
@@ -370,6 +396,12 @@ typedef enum {
   /* maximum number of open connections in total */
   CINIT(MAX_TOTAL_CONNECTIONS, LONG, 13),
 
+   /* This is the server push callback function pointer */
+  CINIT(PUSHFUNCTION, FUNCTIONPOINT, 14),
+
+  /* This is the argument passed to the server push callback */
+  CINIT(PUSHDATA, OBJECTPOINT, 15),
+
   CURLMOPT_LASTENTRY /* the last unused */
 } CURLMoption;