mirror of
https://github.com/curl/curl.git
synced 2024-11-21 01:16:58 +08:00
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:
|
||||
(by Ralph Beckmann <rabe@uni-paderborn.de>)
|
||||
How To Use Libcurl In Your Program
|
||||
|
||||
NOTE: If you plan to use libcurl.a in Threads under Linux, do not use the old
|
||||
gcc-2.7.x because the function 'gethostbyname' seems not to be thread-safe,
|
||||
that is to say an unavoidable SEGMENTATION FAULT might occur.
|
||||
Interfaces
|
||||
|
||||
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:
|
||||
#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);
|
||||
CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...);
|
||||
|
||||
3. size_t handle_data (const void *ptr, size_t size, size_t nitems,
|
||||
FILE *stream)
|
||||
{
|
||||
(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;
|
||||
}
|
||||
CURLcode curl_easy_perform(CURL *curl);
|
||||
void curl_easy_cleanup(CURL *curl);
|
||||
|
||||
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