libcurl v7 adjustments
This commit is contained in:
Daniel Stenberg
parent
7c37c6a8e9
commit
dc98405114
@ -5,104 +5,45 @@
|
|||||||
|_|_|_.__/ \___|\__,_|_| |_|
|
|_|_|_.__/ \___|\__,_|_| |_|
|
||||||
|
|
||||||
|
|
||||||
How To Use Libcurl In Your Program:
|
How To Use Libcurl In Your Program
|
||||||
(by Ralph Beckmann <rabe@uni-paderborn.de>)
|
|
||||||
|
|
||||||
NOTE: If you plan to use libcurl.a in Threads under Linux, do not use the old
|
Interfaces
|
||||||
gcc-2.7.x because the function 'gethostbyname' seems not to be thread-safe,
|
|
||||||
that is to say an unavoidable SEGMENTATION FAULT might occur.
|
libcurl currently offers two different interfaces to the URL transfer
|
||||||
|
engine. They can be seen as one low-level and one high-level, in the sense
|
||||||
|
that the low-level one will allow you to deal with a lot more details but on
|
||||||
|
the other hand not offer as many fancy features (such as Location:
|
||||||
|
following). The high-level interface is supposed to be a built-in
|
||||||
|
implementation of the low-level interface. You will not be able to mix
|
||||||
|
function calls from the different layers.
|
||||||
|
|
||||||
|
As we currently ONLY support the high-level interface, the so called easy
|
||||||
|
interface, I will not attempt to describe any low-level functions at this
|
||||||
|
point.
|
||||||
|
|
||||||
|
Function descriptions
|
||||||
|
|
||||||
|
The interface is meant to be very simple for very simple
|
||||||
|
implementations. Thus, we have minimized the number of entries.
|
||||||
|
|
||||||
|
Main Operations
|
||||||
|
|
||||||
|
You INIT the lib
|
||||||
|
|
||||||
|
You SET OPTIONS you want the lib to use.
|
||||||
|
|
||||||
|
You tell the lib to PERFORM the transfer.
|
||||||
|
|
||||||
|
You CLEAN UP the lib
|
||||||
|
|
||||||
|
done.
|
||||||
|
|
||||||
|
See the separate man pages for the libcurl functions for details.
|
||||||
|
|
||||||
|
|
||||||
1. a) In a C-Program:
|
CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...);
|
||||||
#include "curl.h"
|
|
||||||
|
|
||||||
b) In a C++-Program:
|
|
||||||
extern "C" {
|
|
||||||
#include "curl.h"
|
|
||||||
}
|
|
||||||
|
|
||||||
2. char *url="http://www.domain.com";
|
|
||||||
curl_urlget (URGTAG_URL, url,
|
|
||||||
URGTAG_FLAGS, CONF_NOPROGRESS,
|
|
||||||
URGTAG_ERRORBUFFER, errorBuffer,
|
|
||||||
URGTAG_WRITEFUNCTION, (size_t (*)(void *, int, int, FILE
|
|
||||||
*))handle_data,
|
|
||||||
URGTAG_TIMEOUT, 30, /* or anything You want */
|
|
||||||
...
|
|
||||||
URGTAG_DONE);
|
|
||||||
|
|
||||||
3. size_t handle_data (const void *ptr, size_t size, size_t nitems,
|
CURLcode curl_easy_perform(CURL *curl);
|
||||||
FILE *stream)
|
void curl_easy_cleanup(CURL *curl);
|
||||||
{
|
|
||||||
(void)stream; /* stop complaining using g++ -Wall */
|
|
||||||
if ((int)nitems <= 0) {
|
|
||||||
return (size_t)0;
|
|
||||||
}
|
|
||||||
fprintf(stdout, (char *)ptr); /* or do anything else with it */
|
|
||||||
return nitems;
|
|
||||||
}
|
|
||||||
|
|
||||||
4. Compile Your Program with -I$(CURL_DIR)/include
|
|
||||||
|
|
||||||
5. Link Your Program together with $(CURL_DIR)/lib/libcurl.a
|
|
||||||
|
|
||||||
Small Example of How To Use libcurl
|
|
||||||
|
|
||||||
----------------------------------------------------------------------
|
|
||||||
/* Full example that uses libcurl.a to fetch web pages. */
|
|
||||||
/* curlthreads.c */
|
|
||||||
/* - Test-Program by Ralph Beckmann for using curl in POSIX-Threads */
|
|
||||||
/* Change *url1 and *url2 to textual long and slow non-FRAMESET websites! */
|
|
||||||
/*
|
|
||||||
1. Compile with gcc or g++ as $(CC):
|
|
||||||
$(CC) -c -Wall -pedantic curlthreads.c -I$(CURL_DIR)/include
|
|
||||||
|
|
||||||
2. Link with:
|
|
||||||
- Linux:
|
|
||||||
$(CC) -o curlthreads curlthreads.o $(CURL_DIR)/lib/libcurl.a -lpthread
|
|
||||||
-lm
|
|
||||||
- Solaris:
|
|
||||||
$(CC) -o curlthreads curlthreads.o $(CURL_DIR)/lib/libcurl.a -lpthread
|
|
||||||
-lm -lsocket -lnsl
|
|
||||||
*/
|
|
||||||
|
|
||||||
#include <pthread.h>
|
|
||||||
#include <stdio.h>
|
|
||||||
#ifdef __cplusplus
|
|
||||||
extern "C" {
|
|
||||||
#include "curl.h"
|
|
||||||
}
|
|
||||||
#else
|
|
||||||
#include "curl.h"
|
|
||||||
#endif
|
|
||||||
|
|
||||||
size_t storedata (const void *ptr, size_t size, size_t nitems, FILE *stream) {
|
|
||||||
(void)ptr; (void)stream; /* just to stop g++ -Wall complaining */
|
|
||||||
fprintf(stdout, "Thread #%i reads %i Bytes.\n",
|
|
||||||
(int)pthread_self(), (int)(nitems*size));
|
|
||||||
return (nitems);
|
|
||||||
}
|
|
||||||
|
|
||||||
void *urlfetcher(void *url) {
|
|
||||||
curl_urlget (URGTAG_URL, url,
|
|
||||||
URGTAG_FLAGS, CONF_NOPROGRESS | CONF_FAILONERROR,
|
|
||||||
URGTAG_WRITEFUNCTION, (size_t (*)(void *, int, int, FILE
|
|
||||||
*))storedata,
|
|
||||||
URGTAG_DONE);
|
|
||||||
return NULL;
|
|
||||||
}
|
|
||||||
|
|
||||||
int main(void) {
|
|
||||||
char *url1="www.sun.com";
|
|
||||||
char *url2="www.microsoft.com";
|
|
||||||
|
|
||||||
pthread_t thread_id1, thread_id2;
|
|
||||||
pthread_create(&thread_id1, NULL, urlfetcher, (void *)url1);
|
|
||||||
pthread_create(&thread_id2, NULL, urlfetcher, (void *)url2);
|
|
||||||
pthread_join(thread_id1, NULL);
|
|
||||||
pthread_join(thread_id2, NULL);
|
|
||||||
|
|
||||||
fprintf(stdout, "Ready.\n");
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
|
|||||||
25
docs/curl_easy_cleanup.3
Normal file
25
docs/curl_easy_cleanup.3
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
.\" You can view this file with:
|
||||||
|
.\" nroff -man [file]
|
||||||
|
.\" Written by Daniel.Stenberg@haxx.nu
|
||||||
|
.\"
|
||||||
|
.TH curl_easy_cleanup 3 "22 May 2000" "Curl 7.0" "libcurl Manual"
|
||||||
|
.SH NAME
|
||||||
|
curl_easy_cleanup - End a libcurl "easy" session
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B #include <curl/easy.h>
|
||||||
|
.sp
|
||||||
|
.BI "curl_easy_cleanup(CURL *" handle ");
|
||||||
|
.ad
|
||||||
|
.SH DESCRIPTION
|
||||||
|
This function must be the last function to call for a curl session. It is the
|
||||||
|
opposite of the
|
||||||
|
.I curl_easy_init
|
||||||
|
function and must be called with the same
|
||||||
|
.I handle
|
||||||
|
as input as the curl_easy_init call returned.
|
||||||
|
.SH RETURN VALUE
|
||||||
|
None
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.BR curl_easy_init "(3), "
|
||||||
|
.SH BUGS
|
||||||
|
Surely there are some, you tell me!
|
||||||
25
docs/curl_easy_init.3
Normal file
25
docs/curl_easy_init.3
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
.\" You can view this file with:
|
||||||
|
.\" nroff -man [file]
|
||||||
|
.\" Written by Daniel.Stenberg@haxx.nu
|
||||||
|
.\"
|
||||||
|
.TH curl_easy_init 3 "22 May 2000" "Curl 7.0" "libcurl Manual"
|
||||||
|
.SH NAME
|
||||||
|
curl_easy_init - Start a libcurl "easy" session
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B #include <curl/easy.h>
|
||||||
|
.sp
|
||||||
|
.BI "CURL *curl_easy_init( );"
|
||||||
|
.ad
|
||||||
|
.SH DESCRIPTION
|
||||||
|
This function must be the first function to call, and it returns a CURL handle
|
||||||
|
that you shall use as input to the other easy-functions. The init calls
|
||||||
|
intializes curl and this call MUST have a corresponding call to
|
||||||
|
.I curl_easy_cleanup
|
||||||
|
when the operation is complete.
|
||||||
|
.SH RETURN VALUE
|
||||||
|
If this function returns NULL, something went wrong and you cannot use the
|
||||||
|
other curl functions.
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.BR curl_easy_cleanup "(3), "
|
||||||
|
.SH BUGS
|
||||||
|
Surely there are some, you tell me!
|
||||||
75
docs/curl_easy_setopt.3
Normal file
75
docs/curl_easy_setopt.3
Normal file
@ -0,0 +1,75 @@
|
|||||||
|
.\" You can view this file with:
|
||||||
|
.\" nroff -man [file]
|
||||||
|
.\" Written by Daniel.Stenberg@haxx.nu
|
||||||
|
.\"
|
||||||
|
.TH curl_easy_setopt 3 "22 May 2000" "Curl 7.0" "libcurl Manual"
|
||||||
|
.SH NAME
|
||||||
|
curl_easy_setopt - Set curl easy-session options
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B #include <curl/easy.h>
|
||||||
|
.sp
|
||||||
|
.BI "CURLcode curl_easy_setopt(CURL *" handle ", CURLoption "option ", ...);
|
||||||
|
.ad
|
||||||
|
.SH DESCRIPTION
|
||||||
|
curl_easy_setopt() is called to tell libcurl how to behave in a number of
|
||||||
|
ways. Most operations in libcurl have default actions, and by using the
|
||||||
|
appropriate options you can make them behave differently (as documented). All
|
||||||
|
options are set with the
|
||||||
|
.I option
|
||||||
|
followed by a parameter. That parameter can be a long, a function pointer or
|
||||||
|
an object pointer, all depending on what the option in question expects. Read
|
||||||
|
this manual carefully as bad input values may cause libcurl to behave badly!
|
||||||
|
|
||||||
|
The
|
||||||
|
.I "handle"
|
||||||
|
is the return code from the
|
||||||
|
.I "curl_easy_init"
|
||||||
|
call.
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP 0.8i
|
||||||
|
.B CURLOPT_FILE
|
||||||
|
Data pointer to pass instead of FILE * to the file write function. Note that
|
||||||
|
if you specify the
|
||||||
|
.I CURLOPT_WRITEFUNCTION
|
||||||
|
, this is the pointer you'll get as input.
|
||||||
|
.TP
|
||||||
|
.B CURLOPT_WRITEFUNCTION
|
||||||
|
Function pointer that should use match the following prototype:
|
||||||
|
.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);"
|
||||||
|
This function gets called by libcurl as soon as there is received data that
|
||||||
|
needs to be written down. The size of the data pointed to by
|
||||||
|
.I ptr
|
||||||
|
is
|
||||||
|
.I size
|
||||||
|
multiplied with
|
||||||
|
.I nmemb.
|
||||||
|
Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer).
|
||||||
|
.TP
|
||||||
|
.B CURLOPT_INFILE
|
||||||
|
Data pointer to pass instead of FILE * to the file read function. Note that if
|
||||||
|
you specify the
|
||||||
|
.I CURLOPT_READFUNCTION
|
||||||
|
, this is the pointer you'll get as input.
|
||||||
|
.TP
|
||||||
|
.B CURLOPT_READFUNCTION
|
||||||
|
Function pointer that should use match the following prototype:
|
||||||
|
.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);"
|
||||||
|
This function gets called by libcurl as soon as it needs to read data in order
|
||||||
|
to send it to the peer. The data area pointed at by the pointer
|
||||||
|
.I ptr
|
||||||
|
may be filled with at most
|
||||||
|
.I size
|
||||||
|
multiplied with
|
||||||
|
.I nmemb
|
||||||
|
number of bytes. Your function must return the actual number of bytes that you
|
||||||
|
stored in that memory area. Returning -1 will signal an error to the library
|
||||||
|
and cause it to abort the current transfer immediately.
|
||||||
|
.PP
|
||||||
|
.SH RETURN VALUE
|
||||||
|
0 means the option was set properly, non-zero means an error as
|
||||||
|
.I <curl/curl.h>
|
||||||
|
defines
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), "
|
||||||
|
.SH BUGS
|
||||||
|
Surely there are some, you tell me!
|
||||||
Loading…
Reference in New Issue
Block a user