cocos2d-X 节点（curl.h）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

cocos2d-X 节点（curl.h）API

温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记

///cocos2d-x-3.0alpha0/cocos2dx/platform/third_party/ios/curl
#ifndef __CURL_CURL_H
#define __CURL_CURL_H


/*
 * 如果您有 libcurl 方面的问题，所有的文档和细节在这里找到：
 *   http://curl.haxx.se/libcurl/
 *
 * curl-library 你可以访问下面的 web 页面订阅和退订邮件：
 *   http://cool.haxx.se/mailman/listinfo/curl-library/
 */

#include "curlver.h"         /* libcurl 版本定义   */
#include "curlbuild.h"       /* libcurl 构建定义 */
#include "curlrules.h"       /* libcurl 规则定义 */

/*
 * 定义 Win32 ，当构建目标是 Win32 API
 */

#if (defined(_WIN32) || defined(__WIN32__)) && \
     !defined(WIN32) && !defined(__SYMBIAN32__)
#define WIN32
#endif

#include <stdio.h>
#include <limits.h>

#if defined(__FreeBSD__) && (__FreeBSD__ >= 2)
/* 需要__ FreeBSD_version中的标记定义*/
#include <osreldate.h>
#endif

/* 这里包含下面的东西，其主要是 time_t! */
#include <sys/types.h>
#include <time.h>

#if defined(WIN32) && !defined(_WIN32_WCE) && !defined(__CYGWIN__)
#if !(defined(_WINSOCKAPI_) || defined(_WINSOCK_H) || defined(__LWIP_OPT_H__))
/* 检查 winsock2 包含的内容在 winsock.h 里面是否已经存在，因为他们不能在没有问题的时候共存
*/
#include <winsock2.h>
#include <ws2tcpip.h>
#endif
#endif

/* HP-UX 系统版本是 9, 因为 10 、 11 缺少 sys/select.h 所以基于
   libc5-based Linux 系统不过时. 我们需要系统包含它（sys/select.h）! 
 */
#if defined(_AIX) || defined(__NOVELL_LIBC__) || defined(__NetBSD__) || \
    defined(__minix) || defined(__SYMBIAN32__) || defined(__INTEGRITY) || \
    defined(ANDROID) || defined(__ANDROID__) || \
   (defined(__FreeBSD_version) && (__FreeBSD_version < 800000))
#include <sys/select.h>
#endif

#if !defined(WIN32) && !defined(_WIN32_WCE)
#include <sys/socket.h>
#endif

#if !defined(WIN32) && !defined(__WATCOMC__) && !defined(__VXWORKS__)
#include <sys/time.h>
#endif

#ifdef __BEOS__
#include <support/SupportDefs.h>
#endif

#ifdef  __cplusplus
extern "C" {
#endif

typedef void CURL;

/*
 * Win32 、 Symbian OS DLL 链接的装饰到处功能.
 * 避免使用 .def 文件构建 libcurl.dll.
 */
#if (defined(WIN32) || defined(_WIN32) || defined(__SYMBIAN32__)) && \
     !defined(CURL_STATICLIB)
#if defined(BUILDING_LIBCURL)
#define CURL_EXTERN  __declspec(dllexport)
#else
#define CURL_EXTERN  __declspec(dllimport)
#endif
#else

#ifdef CURL_HIDDEN_SYMBOLS
/*
 * 默认 symbols 是隐藏的，这个定义可以让外部共享库可见  
 * 
 * 编译 library 后，再编译应用程序时，是否设置与否，都没有区别，.
 */
#define CURL_EXTERN CURL_EXTERN_SYMBOL
#else
#define CURL_EXTERN
#endif
#endif

#ifndef curl_socket_typedef
/* socket typedef */
#if defined(WIN32) && !defined(__LWIP_OPT_H__)
typedef SOCKET curl_socket_t;
#define CURL_SOCKET_BAD INVALID_SOCKET
#else
typedef int curl_socket_t;
#define CURL_SOCKET_BAD -1
#endif
#define curl_socket_typedef
#endif /* curl_socket_typedef */

struct curl_httppost {
  struct curl_httppost *next;       /* 在列表中的下一个条目*/
  char *name;                       /* 分配的名字指针 */
  long namelength;                  /* 名字的长度 */
  char *contents;                   /* 分配的内容数据指针 */
  long contentslength;              /* 内容字段的长度	 */
  char *buffer;                     /* 分配的缓冲区内容指针 */
  long bufferlength;                /* 缓冲区内容字段的长度 */
  char *contenttype;                /* 内容类型 */
  struct curl_slist* contentheader; /* 这种样式的附加头列表（www.、 http://、https:// ） */
  struct curl_httppost *more;       /* 如果一个字段名不止指向一个文件，这个链接应该链接到这些文件
                                        */
  long flags;                       /* 在下面定义 */
#define HTTPPOST_FILENAME (1<<0)    /* 指定的内容是文件名 */
#define HTTPPOST_READFILE (1<<1)    /* 指定的内容是文件名 */
#define HTTPPOST_PTRNAME (1<<2)     /* 只存储名字指针
                                       formfree 不是空闲（free）的*/
#define HTTPPOST_PTRCONTENTS (1<<3) /* 只存储 内容指针
                                       formfree 不是空闲（free）的 */
#define HTTPPOST_BUFFER (1<<4)      /* 从缓冲区上传文件 */
#define HTTPPOST_PTRBUFFER (1<<5)   /* 从指针内容上传文件 */
#define HTTPPOST_CALLBACK (1<<6)    /* 通过常规的读 callback 获取数据，上传给定指针指向的文件内容
                                    */

  char *showfilename;               /* T要显示的文件名he file name to show. 如果没有设置将使用真实的文件名, (如果这是文件的一部分)
                                     */
  void *userp;                      /* 自定义指针使用了 HTTPPOST_CALLBACK posts 
                                     */
};

typedef int (*curl_progress_callback)(void *clientp,
                                      double dltotal,
                                      double dlnow,
                                      double ultotal,
                                      double ulnow);

#ifndef CURL_MAX_WRITE_SIZE
  /* 实验证明 20 k 在 windosw 上是一个糟糕的上载缓冲区大小，一些奇怪的原因 16k 表现好了很多。我们的 ifndef 检查，允许该值更容易被那些爱冒险的人改变改变
     实际上最小值大概是 400 bytes，自 libcurl 使用一个 buffer 它的大小从无到有(和网络发送操作无关).
   */
#define CURL_MAX_WRITE_SIZE 16384
#endif

#ifndef CURL_MAX_HTTP_HEADER
/* 有一个风险是应该避免的，使用 libcurl 的一个never-ending 的 header 可能会导致服务器无限循环的执行一个请求
*/
#define CURL_MAX_HTTP_HEADER (100*1024)
#endif

/* return 一个有魔力的 write callback ,返回时,libcurl 会收到暂停接受当前传输的信号
 */
#define CURL_WRITEFUNC_PAUSE 0x10000001

typedef size_t (*curl_write_callback)(char *buffer,
                                      size_t size,
                                      size_t nitems,
                                      void *outstream);



/* 枚举文件类型 */
typedef enum {
  CURLFILETYPE_FILE = 0,
  CURLFILETYPE_DIRECTORY,
  CURLFILETYPE_SYMLINK,
  CURLFILETYPE_DEVICE_BLOCK,
  CURLFILETYPE_DEVICE_CHAR,
  CURLFILETYPE_NAMEDPIPE,
  CURLFILETYPE_SOCKET,
  CURLFILETYPE_DOOR, /* 现在可能只在 Sun Solaris */

  CURLFILETYPE_UNKNOWN /* 应该永远不会发生 */
} curlfiletype;

#define CURLFINFOFLAG_KNOWN_FILENAME    (1<<0)
#define CURLFINFOFLAG_KNOWN_FILETYPE    (1<<1)
#define CURLFINFOFLAG_KNOWN_TIME        (1<<2)
#define CURLFINFOFLAG_KNOWN_PERM        (1<<3)
#define CURLFINFOFLAG_KNOWN_UID         (1<<4)
#define CURLFINFOFLAG_KNOWN_GID         (1<<5)
#define CURLFINFOFLAG_KNOWN_SIZE        (1<<6)
#define CURLFINFOFLAG_KNOWN_HLINKCOUNT  (1<<7)

    /* 结构体里面的内容依赖于现实中的已知的信息 (e.g. 通过 FTP LIST 解析). 请看 url_easy_setopt（3）手册这个结构体的 callbacks returning  -- 一些字段是强制性的，
       另一些字段是可选的。标志字段具有特殊的意义. */
struct curl_fileinfo {
  char *filename;
  curlfiletype filetype;
  time_t time;
  unsigned int perm;
  int uid;
  int gid;
  curl_off_t size;
  long int hardlinks;

  struct {
    /* 如果一些字段不为 NULL, 他是一个指向 b_data 的指针. */
    char *time;
    char *perm;
    char *user;
    char *group;
    char *target; /* 一个指向 symlink 目标文件名的指针 */
  } strings;

  unsigned int flags;

  /* 内部使用 */
  char * b_data;
  size_t b_size;
  size_t b_used;
};

/* return  CURLOPT_CHUNK_BGN_FUNCTION 功能的代码*/
#define CURL_CHUNK_BGN_FUNC_OK      0
#define CURL_CHUNK_BGN_FUNC_FAIL    1 /* 告诉的lib结束任务 */
#define CURL_CHUNK_BGN_FUNC_SKIP    2 /* 跳过这个块 */

/*  如果启用了数据分割传输，那么开始一个单独数据块下载前这个 callback 被调用
    请注意 "remains" 参数，只在 FTP 通配符，下载时使用，其他情况不使用
*/
typedef long (*curl_chunk_bgn_callback)(const void *transfer_info,
                                        void *ptr,
                                        int remains);

/* return CURLOPT_CHUNK_END_FUNCTION 功能的代码*/
#define CURL_CHUNK_END_FUNC_OK      0
#define CURL_CHUNK_END_FUNC_FAIL    1 /* 告诉的lib结束任务 */

/* 如果启用了数据分割传输 ，如果启用了数据分割传输，那么结束一个单独数据块下载后这个 callback 被调用.
   请注意! 所有的快都会调用这个回调函数.
   即使这个下载块在 CHUNK_BGN_FUNC 里面被跳过了。.
   这就是为什么我们故需要 "transfer_info" 参数 ，为什么我们不关心 "remains" 参数的原因. */
typedef long (*curl_chunk_end_callback)(void *ptr);

/* return  FNMATCHFUNCTION 功能的代码 */
#define CURL_FNMATCHFUNC_MATCH    0 /* 字符串对应的模式 */
#define CURL_FNMATCHFUNC_NOMATCH  1 /* 模式不匹配的字符串 */
#define CURL_FNMATCHFUNC_FAIL     2 /* 发生了错误 */

/* 通配符下载模式匹配的回调类型. 
   字符串匹配的模式, return CURL_FNMATCHFUNC_MATCH 值, etc. */
typedef int (*curl_fnmatch_callback)(void *ptr,
                                     const char *pattern,
                                     const char *string);

/* 这些返回代码是关于 seek（请求） callbacks */
#define CURL_SEEKFUNC_OK       0
#define CURL_SEEKFUNC_FAIL     1 /* 整个传输失败 */
#define CURL_SEEKFUNC_CANTSEEK 2 /* 告诉 libcurl （请求）seeking 不可达, 
                                    所以 libcurl 可能尝试其它的方法来代替 */
typedef int (*curl_seek_callback)(void *instream,
                                  curl_off_t offset,
                                  int origin); /* 'whence' */   ;// 和出

/*一个 read callback ,返回时,libcurl 会收到立即中止当前传输的信号 
*/
#define CURL_READFUNC_ABORT 0x10000000
/* 一个 read callback ,返回时,libcurl 会收到暂停发送数据当前传输的信号 . */
#define CURL_READFUNC_PAUSE 0x10000001

typedef size_t (*curl_read_callback)(char *buffer,
                                      size_t size,
                                      size_t nitems,
                                      void *instream);

typedef enum  {
  CURLSOCKTYPE_IPCXN, /* 创建一个特定的IP连接的插座 socket */
  CURLSOCKTYPE_LAST   /* never use */
} curlsocktype;

/* 返回 libcurl  sockopt_callback 的信号信息: */
#define CURL_SOCKOPT_OK 0
#define CURL_SOCKOPT_ERROR 1 /* 导致libcurl的中止，并返回
                                CURLE_ABORTED_BY_CALLBACK */
#define CURL_SOCKOPT_ALREADY_CONNECTED 2

typedef int (*curl_sockopt_callback)(void *clientp,
                                     curl_socket_t curlfd,
                                     curlsocktype purpose);

struct curl_sockaddr {
  int family;
  int socktype;
  int protocol;
  unsigned int addrlen; /*  addrlen 是一个 socklen_t 类型，在7.780 前缺少这种类型
                           turned 信息非常难懂
                           */
  struct sockaddr addr;
};

typedef curl_socket_t
(*curl_opensocket_callback)(void *clientp,
                            curlsocktype purpose,
                            struct curl_sockaddr *address);

typedef int
(*curl_closesocket_callback)(void *clientp, curl_socket_t item);

typedef enum {
  CURLIOE_OK,            /* I/O 操作成功 */
  CURLIOE_UNKNOWNCMD,    /* 命令是未知的回调*/
  CURLIOE_FAILRESTART,   /* 未能重新读取 */
  CURLIOE_LAST           /* never use */
} curlioerr;

typedef enum  {
  CURLIOCMD_NOP,         /* 无操作*/
  CURLIOCMD_RESTARTREAD, /* 重新启动读取流 */
  CURLIOCMD_LAST         /* never use */
} curliocmd;

typedef curlioerr (*curl_ioctl_callback)(CURL *handle,
                                         int cmd,
                                         void *clientp);

/*
 * 下列 typedef's 签名包括 malloc, free, realloc, strdup and
 * calloc respectively. 这些类型的函数指针可以被传递到
 * curl_global_init_mem() 函数来设置用户定义的内存管理回调程序。
 */
typedef void *(*curl_malloc_callback)(size_t size);
typedef void (*curl_free_callback)(void *ptr);
typedef void *(*curl_realloc_callback)(void *ptr, size_t size);
typedef char *(*curl_strdup_callback)(const char *str);
typedef void *(*curl_calloc_callback)(size_t nmemb, size_t size);

/* 数据类型传递给 information_callback*/
typedef enum {
  CURLINFO_TEXT = 0,
  CURLINFO_HEADER_IN,    /* 1 */
  CURLINFO_HEADER_OUT,   /* 2 */
  CURLINFO_DATA_IN,      /* 3 */
  CURLINFO_DATA_OUT,     /* 4 */
  CURLINFO_SSL_DATA_IN,  /* 5 */
  CURLINFO_SSL_DATA_OUT, /* 6 */
  CURLINFO_END
} curl_infotype;

typedef int (*curl_debug_callback)
       (CURL *handle,      /* 这涉及 处理/传输 */
        curl_infotype type, /* 什么类型的数据 */
        char *data,        /* 指向数据*/
        size_t size,       /* 数据大小   */
        void *userptr);    /* 请求的任何用户 */

/* 所有可能的 curl 功能错误代码种类
 未来的版本可能返回其他值, 留的准备。

 最后随时添加新的返回代码. 从不* EVER *删除。返回
 代码必须保持一致！
 */

typedef enum {
  CURLE_OK = 0,
  CURLE_UNSUPPORTED_PROTOCOL,    /* 1 */
  CURLE_FAILED_INIT,             /* 2 */
  CURLE_URL_MALFORMAT,           /* 3 */
  CURLE_NOT_BUILT_IN,