opts: more multi options as stand-alone man pages

13 files changed, 319 insertions, 7 deletions

diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
new file mode 100644
index 000000000..66ceab822
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
@@ -0,0 +1,48 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_CHUNK_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, long size);
+.SH DESCRIPTION
+Pass a long with a \fBsize\fP in bytes. If a pipelined connection is currently
+processing a chunked (Transfer-encoding: chunked) request with a current chunk
+length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, that pipeline
+will not be considered for additional requests, even if it is shorter than
+\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
+.SH DEFAULT
+The default value is 0, which means that the penalization is inactive.
+.SH PROTOCOLS
+HTTP(S)
+.SH EXAMPLE
+TODO
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), "
+.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
new file mode 100644
index 000000000..203b6acce
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
@@ -0,0 +1,47 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_CONTENT_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, long size);
+.SH DESCRIPTION
+Pass a long with a \fBsize\fP in bytes. If a pipelined connection is currently
+processing a request with a Content-Length larger than this
+\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline will then not be
+considered for additional requests, even if it is shorter than
+\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
+.SH DEFAULT
+The default value is 0, which means that the size penalization is inactive.
+.SH PROTOCOLS
+HTTP(S)
+.SH EXAMPLE
+TODO
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
index eb2560b39..759ce0862 100644
--- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
+++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
@@ -26,7 +26,7 @@ CURLMOPT_MAXCONNECTS \- set size of connection cache
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_MAXCONNECTS, long max);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max);
 .SH DESCRIPTION
 Pass a long indicating the \fBmax\fP. The set number will be used as the
 maximum amount of simultaneously open connections that libcurl may keep in its
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
index 27301a629..778934737 100644
--- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
+++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
@@ -26,7 +26,7 @@ CURLMOPT_MAX_HOST_CONNECTIONS \- set max number of connections to a single host
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max);
 .SH DESCRIPTION
 Pass a long to indicate \fBmax\fP. The set number will be used as the maximum
 amount of simultaneously open connections to a single host. For each new
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
new file mode 100644
index 000000000..c2adb457e
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
@@ -0,0 +1,51 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_MAX_PIPELINE_LENGTH 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, long max);
+.SH DESCRIPTION
+Pass a long. The set \fBmax\fP number will be used as the maximum amount of
+outstanding requests in a pipelined connection. Only used if pipelining is
+enabled.
+
+When this limit is reached, libcurl will use another connection to the same
+host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until
+one of the pipelines to the host is ready to accept a request.  Thus, the
+total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP *
+\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
+.SH DEFAULT
+5
+.SH PROTOCOLS
+HTTP(S)
+.SH EXAMPLE
+TODO
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
new file mode 100644
index 000000000..2783a7d87
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
@@ -0,0 +1,50 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_MAX_TOTAL_CONNECTIONS 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, long amount);
+.SH DESCRIPTION
+Pass a long for the \fBamount\fP. The set number will be used as the maximum
+number of simultaneously open connections in total using this multi
+handle. For each new session, libcurl will open a new connection up to the
+limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is
+reached, the sessions will be pending until there are available
+connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to
+pipeline if the host is capable of it.
+.SH DEFAULT
+The default value is 0, which means that there is no limit. It is then simply
+controlled by the number of easy handles added.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+TODO
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3
index ce6bd9b64..c1df1d560 100644
--- a/docs/libcurl/opts/CURLMOPT_PIPELINING.3
+++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.3
@@ -26,7 +26,7 @@ CURLMOPT_PIPELINING \- enable/disable HTTP pipelining
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_PIPELINING, bool onoff);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, bool onoff);
 .SH DESCRIPTION
 Set the \fBonoff\fP parameter to 1 to make libcurl use HTTP pipelining for
 HTTP transfers done using this multi handle, as far as possible. This means
diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3
new file mode 100644
index 000000000..ae393121e
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3
@@ -0,0 +1,60 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_PIPELINING_SERVER_BL 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_PIPELINING_SERVER_BL \- pipelining server blacklist
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL, char **servers);
+.SH DESCRIPTION
+Pass a \fBservers\fP array of char *, ending with a NULL entry. This is a list
+of server types prefixes (in the Server: HTTP header) that are blacklisted
+from pipelining, i.e server types that are known to not support HTTP
+pipelining. The array is copied by libcurl.
+
+Note that the comparison matches if the Server: header begins with the string
+in the blacklist, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can 
+both be blacklisted by having "Ninja" in the backlist.
+
+Pass a NULL pointer to clear the blacklist.
+.SH DEFAULT
+The default value is NULL, which means that there is no blacklist.
+.SH PROTOCOLS
+.SH EXAMPLE
+.nf
+  server_blacklist[] =
+  {
+    "Microsoft-IIS/6.0",
+    "nginx/0.8.54",
+    NULL
+  };
+
+  curl_multi_setopt(m, CURLMOPT_PIPELINE_SERVER_BL, server_blacklist);
+.fi
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SITE_BL "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3
new file mode 100644
index 000000000..6356d02f0
--- /dev/null
+++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3
@@ -0,0 +1,56 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, 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_PIPELINING_SITE_BL 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
+.SH NAME
+CURLMOPT_PIPELINING_SITE_BL \- pipelining host blacklist
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL, char **hosts);
+.SH DESCRIPTION
+Pass a \fBhosts\fP array of char *, ending with a NULL entry. This is a list
+of sites that are blacklisted from pipelining, i.e sites that are known to not
+support HTTP pipelining. The array is copied by libcurl.
+
+Pass a NULL pointer to clear the blacklist.
+.SH DEFAULT
+The default value is NULL, which means that there is no blacklist.
+.SH PROTOCOLS
+HTTP(S)
+.SH EXAMPLE
+.nf
+  site_blacklist[] =
+  {
+    "www.haxx.se",
+    "www.example.com:1234",
+    NULL
+  };
+
+  curl_multi_setopt(m, CURLMOPT_PIPELINE_SITE_BL, site_blacklist);
+.fi
+.SH AVAILABILITY
+Added in 7.30.0
+.SH RETURN VALUE
+Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SERVER_BL "(3), "
diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3
index 49665b985..bf7e6a757 100644
--- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3
+++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3
@@ -27,7 +27,7 @@ CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback
 .nf
 #include <curl/curl.h>
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_SOCKETDATA, void *pointer);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer);
 .SH DESCRIPTION
 A data \fIpointer\fP to pass to the socket callback set with the
 \fICURLMOPT_SOCKETFUNCTION(3)\fP option.
diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
index 3fd3bb2c2..d64fe112f 100644
--- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
+++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
@@ -33,7 +33,7 @@ int socket_callback(CURL *easy,      /* easy handle */
                     void *userp,     /* private callback pointer */
                     void *socketp);  /* private socket pointer */
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
 .SH DESCRIPTION
 Pass a pointer to your callback function, which should match the prototype
 shown above.
diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
index 78cfcfb53..41627da1d 100644
--- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
+++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
@@ -27,7 +27,7 @@ CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback
 .nf
 #include <curl/curl.h>
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_TIMERDATA, void *pointer);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer);
 .SH DESCRIPTION
 A data \fBpointer\fP to pass to the timer callback set with the
 \fICURLMOPT_TIMERFUNCTION(3)\fP option.
diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
index 743aa99eb..809c3ef5b 100644
--- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
+++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
@@ -31,7 +31,7 @@ int timer_callback(CURLM *multi,    /* multi handle */
                    long timeout_ms, /* see above */
                    void *userp);    /* private callback pointer */
 
-CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
 .SH DESCRIPTION
 Pass a pointer to your callback function, which should match the prototype
 shown above.