From d02587750ccea0c5cb2e3e15357279c1f42a496b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Apr 2004 07:11:06 +0000 Subject: added function headers and comments --- lib/connect.c | 33 +++++++++++++++++++++------------ lib/easy.c | 43 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 56 insertions(+), 20 deletions(-) (limited to 'lib') diff --git a/lib/connect.c b/lib/connect.c index 24663289d..088ca3034 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -104,6 +104,10 @@ static bool verifyconnect(curl_socket_t sockfd); +/* + * Curl_ourerrno() returns the errno (or equivalent) on this platform to + * hide platform specific for the function that calls this. + */ int Curl_ourerrno(void) { #ifdef WIN32 @@ -113,13 +117,11 @@ int Curl_ourerrno(void) #endif } -/************************************************************************* - * Curl_nonblock - * - * Description: - * Set the socket to either blocking or non-blocking mode. +/* + * Curl_nonblock() set the given socket to either blocking or non-blocking + * mode based on the 'nonblock' boolean argument. This function is highly + * portable. */ - int Curl_nonblock(curl_socket_t sockfd, /* operate on this */ int nonblock /* TRUE or FALSE */) { @@ -177,12 +179,19 @@ int Curl_nonblock(curl_socket_t sockfd, /* operate on this */ } /* - * waitconnect() returns: + * waitconnect() waits for a TCP connect on the given socket for the specified + * number if milliseconds. It returns: * 0 fine connect * -1 select() error * 1 select() timeout - * 2 select() returned with an error condition + * 2 select() returned with an error condition fd_set */ + +#define WAITCONN_CONNECTED 0 +#define WAITCONN_SELECT_ERROR -1 +#define WAITCONN_TIMEOUT 1 +#define WAITCONN_FDSET_ERROR 2 + static int waitconnect(curl_socket_t sockfd, /* socket */ long timeout_msec) @@ -213,18 +222,18 @@ int waitconnect(curl_socket_t sockfd, /* socket */ rc = select(sockfd+1, NULL, &fd, &errfd, &interval); if(-1 == rc) /* error, no connect here, try next */ - return -1; + return WAITCONN_SELECT_ERROR; else if(0 == rc) /* timeout, no connect today */ - return 1; + return WAITCONN_TIMEOUT; if(FD_ISSET(sockfd, &errfd)) /* error condition caught */ - return 2; + return WAITCONN_FDSET_ERROR; /* we have a connect! */ - return 0; + return WAITCONN_CONNECTED; } static CURLcode bindlocal(struct connectdata *conn, diff --git a/lib/easy.c b/lib/easy.c index bc91f4874..fc3f96963 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -85,14 +85,16 @@ #include "memdebug.h" #endif -/* Silly win32 socket initialization functions */ - #if defined(WIN32) && !defined(__GNUC__) || defined(__MINGW32__) +/* win32_cleanup() is for win32 socket cleanup functionality, the opposite + of win32_init() */ static void win32_cleanup(void) { WSACleanup(); } +/* win32_init() performs win32 socket initialization to properly setup the + stack to allow networking */ static CURLcode win32_init(void) { WORD wVersionRequested; @@ -126,23 +128,23 @@ static CURLcode win32_init(void) WSACleanup(); return CURLE_FAILED_INIT; } + /* The Windows Sockets DLL is acceptable. Proceed. */ return CURLE_OK; } -/* The Windows Sockets DLL is acceptable. Proceed. */ + #else /* These functions exist merely to prevent compiler warnings */ static CURLcode win32_init(void) { return CURLE_OK; } static void win32_cleanup(void) { } #endif - /* true globals -- for curl_global_init() and curl_global_cleanup() */ static unsigned int initialized = 0; static long init_flags = 0; /** - * Globally initializes cURL given a bitwise set of - * the different features to initialize. + * curl_global_init() globally initializes cURL given a bitwise set of the + * different features of what to initialize. */ CURLcode curl_global_init(long flags) { @@ -168,8 +170,8 @@ CURLcode curl_global_init(long flags) } /** - * Globally cleanup cURL, uses the value of "init_flags" to determine - * what needs to be cleaned up and what doesn't + * curl_global_cleanup() globally cleanups cURL, uses the value of + * "init_flags" to determine what needs to be cleaned up and what doesn't. */ void curl_global_cleanup(void) { @@ -192,6 +194,10 @@ void curl_global_cleanup(void) init_flags = 0; } +/* + * curl_easy_init() is the external interface to alloc, setup and init an + * easy handle that is returned. If anything goes wrong, NULL is returned. + */ CURL *curl_easy_init(void) { CURLcode res; @@ -213,6 +219,10 @@ CURL *curl_easy_init(void) return data; } +/* + * curl_easy_setopt() is the external interface for setting options on an + * easy handle. + */ typedef int (*func_T)(void); CURLcode curl_easy_setopt(CURL *curl, CURLoption tag, ...) { @@ -257,6 +267,10 @@ CURLcode curl_easy_setopt(CURL *curl, CURLoption tag, ...) return ret; } +/* + * curl_easy_perform() is the external interface that performs a transfer + * previously setup. + */ CURLcode curl_easy_perform(CURL *curl) { struct SessionHandle *data = (struct SessionHandle *)curl; @@ -285,6 +299,10 @@ CURLcode curl_easy_perform(CURL *curl) return Curl_perform(data); } +/* + * curl_easy_cleanup() is the external interface to cleaning/freeing the given + * easy handle. + */ void curl_easy_cleanup(CURL *curl) { struct SessionHandle *data = (struct SessionHandle *)curl; @@ -296,6 +314,10 @@ void curl_easy_cleanup(CURL *curl) Curl_close(data); } +/* + * curl_easy_getinfo() is an external interface that allows an app to retrieve + * information from a performed transfer and similar. + */ CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ...) { va_list arg; @@ -308,6 +330,11 @@ CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ...) return Curl_getinfo(data, info, paramp); } +/* + * curl_easy_duphandle() is an external interface to allow duplication of a + * given input easy handle. The returned handle will be a new working handle + * with all options set exactly as the input source handle. + */ CURL *curl_easy_duphandle(CURL *incurl) { struct SessionHandle *data=(struct SessionHandle *)incurl; -- cgit v1.2.3