libcurl v7 adjustments

                        |_|_|_.__/ \___|\__,_|_|  |_|

                     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

gcc-2.7.x because the function 'gethostbyname' seems not to be thread-safe,

that is to say an unavoidable SEGMENTATION FAULT might occur.

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);

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;

}

                     How To Use Libcurl In Your Program

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.

        CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...);

CURLcode curl_easy_perform(CURL *curl);

void curl_easy_cleanup(CURL *curl);

.\" 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!

.\" 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!

.\" 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!