generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[Hiper-related work] Added a function called curl_multi_assign() that will

Browse Source 
set a private pointer added to the internal libcurl hash table for the
particular socket passed in to this function.
This commit is contained in:
Daniel Stenberg
2006-07-26 22:19:42 +00:00
parent 45b1843dc9
commit 6f6b93da02
10 changed files with 204 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/libcurl/Makefile.am
View File

@@ -18,7 +18,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \
curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \
libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \
curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \
curl_multi_timeout.3 curl_formget.3
curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3
HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \
curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \
@@ -35,8 +35,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \
libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \
curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \
curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \
curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \
curl_formget.html
curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \
curl_formget.html curl_multi_assign.html
PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \
@@ -52,8 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \
curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \
curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \
curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \
curl_formget.pdf
curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \
curl_formget.pdf curl_multi_assign.pdf
CLEANFILES = $(HTMLPAGES) $(PDFPAGES)

34
docs/libcurl/curl_global_init.3
View File

@@ -11,30 +11,30 @@ curl_global_init - Global libcurl initialisation
.BI "CURLcode curl_global_init(long " flags ");"
.ad
.SH DESCRIPTION
This function sets up the program environment that libcurl needs. Think
of it as an extension of the library loader.
This function sets up the program environment that libcurl needs. Think of it
as an extension of the library loader.
This function must be called at least once within a program (a program is
all the code that shares a memory space) before the program calls any other
function in libcurl. The environment it sets up is constant for the life
of the program and is the same for every program, so multiple calls have
the same effect as one call.
This function must be called at least once within a program (a program is all
the code that shares a memory space) before the program calls any other
function in libcurl. The environment it sets up is constant for the life of
the program and is the same for every program, so multiple calls have the same
effect as one call.
The flags option is a bit pattern that tells libcurl exactly what features to
init, as described below. Set the desired bits by ORing the values together.
In normal operation, you must specify CURL_GLOBAL_ALL. Don't use any other
value unless you are familiar with and mean to control internal operations
of libcurl.
value unless you are familiar with and mean to control internal operations of
libcurl.
\fBThis function is not thread safe.\fP You must not call it when any
other thread in the program (i.e. a thread sharing the same memory) is
running. This doesn't just mean no other thread that is using
libcurl. Because \fIcurl_global_init()\fP calls functions of other
libraries that are similarly thread unsafe, it could conflict with any
other thread that uses these other libraries.
\fBThis function is not thread safe.\fP You must not call it when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This doesn't just mean no other thread that is using libcurl. Because
\fIcurl_global_init()\fP calls functions of other libraries that are similarly
thread unsafe, it could conflict with any other thread that uses these other
libraries.
See the description in \fBlibcurl\fP(3) of global environment
requirements for details of how to use this function.
See the description in \fBlibcurl\fP(3) of global environment requirements for
details of how to use this function.
.SH FLAGS
.TP 5

44
docs/libcurl/curl_multi_assign.3 Normal file
View File

@@ -0,0 +1,44 @@
.\" $Id$
.\"
.TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"
.SH NAME
curl_multi_assign \- set data to associated with an internal socket
.SH SYNOPSIS
#include <curl/curl.h>
CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
void *sockptr);
.SH DESCRIPTION
This function assigns an association in the multi handle between the given
socket and a private pointer of the application. This is (only) useful for
\fIcurl_multi_socket(3)\fP uses.
When set, the \fIsockptr\fP pointer will be passed to all future socket
callbacks for the specific \fIsockfd\fP socket.
If the given \fIsockfd\fP isn't already in use by libcurl, this function will
return an error.
libcurl only keeps one single pointer associated with a socket, so calling
this function several times for the same socket will make the last set pointer
get used.
The idea here being that this association (socket to private pointer) is
something that just about every application that uses this API will need and
then libcurl can just as well do it since it already has an internal hash
table lookup for this.
.SH "RETURN VALUE"
The standard CURLMcode for multi interface error codes.
.SH "TYPICAL USAGE"
In a typical application you allocate a struct or at least use some kind of
semi-dynamic data for each socket that we must wait for action on when using
the \fIcurl_multi_socket(3)\fP approach.
When our socket-callback get called by libcurl and we get to know about yet
another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
the particular data so that when we get updates about this same socket again,
we don't have to find the struct associated with this socket by ourselves.
.SH AVAILABILITY
This function was added in libcurl 7.15.5, although not deemed stable yet.
.SH "SEE ALSO"
.BR curl_multi_setopt "(3), " curl_multi_socket "(3) "

5
docs/libcurl/curl_multi_setopt.3
View File

@@ -25,8 +25,9 @@ the socket (file descriptor) status by doing none, one or multiple calls to
the curl_socket_callback given in the \fBparam\fP argument. They update the
status with changes since the previous time a \fIcurl_multi_socket(3)\fP
function was called. If the given callback pointer is NULL, no callback will
be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP.
See \fIcurl_multi_socket(3)\fP for more callback details.
be called. Set the callback's \fBuserp\fP argument with
\fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback
details.
.IP CURLMOPT_SOCKETDATA
Pass a pointer to whatever you want passed to the curl_socket_callback's forth
argument, the userp pointer. This is not used by libcurl but only passed-thru

48
docs/libcurl/curl_multi_socket.3
View File

@@ -1,6 +1,6 @@
.\" $Id$
.\"
.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual"
.TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"
.SH NAME
curl_multi_socket \- reads/writes available data
.SH SYNOPSIS
@@ -19,32 +19,41 @@ application has detected action on a socket handled by libcurl, it should call
with the action.
These functions inform the application about updates in the socket (file
descriptor) status by doing none, one or multiple calls to the
curl_socket_callback given with the CURLMOPT_SOCKETFUNCTION option to
descriptor) status by doing none, one or multiple calls to the callback
function set with the CURLMOPT_SOCKETFUNCTION option to
\fIcurl_multi_setopt(3)\fP. They update the status with changes since the
previous time this function was called.
If you want to force libcurl to (re-)check all its internal sockets and
transfers instead of just a single one, you call
\fBcurl_multi_socket_all(3)\fP instead.
To force libcurl to (re-)check all its internal sockets and transfers instead
of just a single one, you call \fBcurl_multi_socket_all(3)\fP.
An application should call \fBcurl_multi_timeout(3)\fP to figure out how long
it should wait for socket actions \- at most \- before doing the timeout
action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP
argument set to CURL_SOCKET_TIMEOUT.
Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to
wait for socket actions \- at most \- before doing the timeout action: call
the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to
CURL_SOCKET_TIMEOUT.
.SH "CALLBACK DETAILS"
The socket \fBcallback\fP function uses a prototype like this
.nf
int curl_socket_callback(CURL *easy, /* easy handle */
curl_socket_t s, /* socket */
int action, /* see values below */
void *userp); /* "private" pointer */
int curl_socket_callback(CURL *easy, /* easy handle */
curl_socket_t s, /* socket */
int action, /* see values below */
void *userp, /* private callback pointer */
void *socketp); /* private socket pointer */
.fi
The callback MUST return 0.
The \fIaction\fP (third) argument to the callback has one of five values:
The \fIeasy\fP argument is a pointer to the easy handle that deals with this
particular socket. Note that a single handle may work with several sockets
simultaneously.
The \fIs\fP argument is the actual socket value as you use it within your
system.
The \fIaction\fP argument to the callback has one of five values:
.RS
.IP "CURL_POLL_NONE (0)"
register, not interested in readiness (yet)
@@ -57,6 +66,15 @@ register, interested in both read and write readiness
.IP "CURL_POLL_REMOVE (4)"
deregister
.RE
The \fIsocketp\fP argument is a private pointer you have previously set with
\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
pointer has been set, socketp will be NULL. This argument is of course a
service to applications that want to keep certain data or structs that are
strictly associated to the given socket.
The \fIuserp\fP argument is a private pointer you have previously set with
\fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option.
.SH "RETURN VALUE"
CURLMcode type, general libcurl multi interface error code.