libcurl v7 adjustments

This commit is contained in:
Daniel Stenberg 2000-05-22 19:02:54 +00:00
parent 7c37c6a8e9
commit dc98405114
4 changed files with 161 additions and 95 deletions

View File

@ -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
View 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
View 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
View 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!