Unity BestHTTP 文档翻译（一）

前言

BestHTTP相比于Unity自身的WWW还是强大很多的，学习过程中，发现只有英文文档，就自己顺便翻译了一下，如有用词不准之处，还望不吝赐教。

Introduction (入门介绍)

private void OnRequestFinished(HTTPRequest request, HTTPResponse response)
{
    Debug.Log("request finish. text received:" + response.DataAsText);
}

GET Requests

void GETFun()
{
    //默认HTTPMethods 是GET
    HTTPRequest request = new HTTPRequest(new Uri("https://baidu.com"), OnRequestFinished);
    request.Send();
}

POST Requests

void POSTFun()
{
    HTTPRequest request = new HTTPRequest(new Uri("http://server.com/path"), HTTPMethods.Post, OnRequestFinished);
    request.AddField("FieldName", "Field Value");
    //不设置字段发布数据，可以使用RawData属性
    request.RawData = Encoding.UTF8.GetBytes("Field Value");
    request.Send();
}

Access The Downloaded Data (使用下载数据)

void DowndLoadImage()
{
    new HTTPRequest(new Uri("http://yourserver.com/path/to/image.png"), (request, response) =>
    {
        //第一种方式
        var tex = new Texture2D(0, 0);
        tex.LoadImage(response.Data);
        //guiTexture.texture = tex; 
        //第二种方式
        //guiTexture.texture = response.DataAsTexture2D;

    }).Send();
}

Switching from WWW （通过www转换）

IEnumerator WWWFun()
{
    HTTPRequest request = new HTTPRequest(new Uri("http://server.com"));
    request.Send();
    yield return StartCoroutine(request);
    Debug.Log("request finish. text received:" + request.Response.DataAsText);
}

Advanced Topics (高级主题)

This section will cover some of the advanced usage that can be done with BestHTTP.
本章将介绍BestHTTP的一些高级用法

Authentication(鉴定)(命名空间)

//Best HTTP supports Basic and Digest authentication through the HTTPRequest’s Credentials property
//最佳的HTTP通过HTTPRequest的凭证属性支持Basic和Digest认证：
void Authentication()
{
    HTTPRequest request = new HTTPRequest(new Uri("http://yourserver.org/auth-path"), (req, resp) =>
    {
        if (resp.StatusCode != 401)
        {
            Debug.Log("Authentication");
        }
        else
        {
            Debug.Log("Not Authentication");
        }
    });

    //Credentials类，保留对远程服务器进行身份验证所需的所有信息
    request.Credentials = new Credentials("usr", "paswd");
    request.Send();
}

Download Streaming

//避免下载大文件耗尽内存，采取缓存已经下载的响应的方式
//需要request.UseStreaming = true;
void DownloadStreaming()
{
    HTTPRequest request = new HTTPRequest(new Uri("http://yourserver.com/bigfile"), (req, resp) =>
    {
        List<byte[]> fragments = resp.GetStreamedFragments();

        using (FileStream fs = new FileStream("pathToSave", FileMode.Append))
        {
            foreach (byte[] data in fragments)
            {
                fs.Write(data, 0, data.Length);
            }

            if (resp.IsStreamingFinished)
            {
                Debug.Log("download finished");
            }
        }
    });

    request.UseStreaming = true;
    request.StreamFragmentSize = 1 * 1024 * 1024;
    request.DisableCache = true;//数据已经本地持久化了，就不需要开启缓存了
    request.Send();

    //每当StreamFragmentSize大小的块下载完成时，回调函数被调用一次
    //当IsStreamingFinished = true时，再被调用一次
}

Upload Streaming

void UplaodStreaming()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), HTTPMethods.Post, (req, resp) => { });
    request.UploadStream = new FileStream("File_To.Upload", FileMode.Open);
    request.Send();
    //当上传完成并且DisposeUploadStream为真时，插件将调用流上的Dispose（）函数
    //如果流的长度未知，则UseUploadStreamLength属性应设置为false
}

Upload Progress Tracking

//可以使用HTTPRequest类的OnUploadProgress事件跟踪上传进度
//OnUploadProgress事件可以和RawData，表单（通过AddField和AddBinaryData）以及UploadStream一起使用
void UploadProgressTracking()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), HTTPMethods.Post, (req, resp) => { Debug.Log("Finish"); });
    request.RawData = Encoding.UTF8.GetBytes("Filed Value");
    request.OnUploadProgress = OnUploadProgress;
    request.Send();
}

void OnUploadProgress(HTTPRequest request,long uploaded,long length)
{
    //计算进度百分比
    float progressPercent = (uploaded / (float)length) * 100.0f;
    Debug.Log("Uploaded: " + progressPercent.ToString("F2") + "%");
}

Caching(命名空间)

//缓存机制在幕后工作，我们唯一要做的就是决定是否启用或禁用它
//如果缓存的响应具有未来日期的“Expires”标头，则BestHTTP将使用缓存响应，而不在服务器上进行验证
//我们可以使用HTTPCacheService类的公共函数获取一些信息并对它进行一些控制
//    BeginMaintainence（）：
void Caching()
{
    //它将开始在单独的线程上清除整个缓存
    HTTPCacheService.BeginClear();

    //通过此函数的帮助，我们可以根据上次访问时间删除缓存条目。它删除上次访问时间比指定时间早的条目,还可以控制缓存大小
    HTTPCacheService.BeginMaintainence(new HTTPCacheMaintananceParams(TimeSpan.FromDays(14), 50 * 1024 * 1024));

    //将以字节为单位返回缓存的大小
    HTTPCacheService.GetCacheSize();

    //将返回缓存中存储的条目数
    HTTPCacheService.GetCacheEntityCount();
}

Cookies (命名空间)

//什么是Cookies？  简单说，一个cookie就是存储在用户主机浏览器中的一小段文本文件
//多数需要登录的站点通常会在你的认证信息通过后来设置一个cookie，之后只要这个cookie存在并且合法，你就可以自由的浏览这个站点的所有部分
//设置请求Cookie头并解析和维护响应的Set-Cookie头由插件自动完成。 但可以通过多种方式进行控制
void Cookies()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => {
        //获取服务端发送给客户端的Cookies
        //resp.Cookies
    });
    request.Cookies.Add(new Cookie("Name", "Value"));
    request.Send();

    //禁用单个请求
    request.IsCookiesEnabled = false;
    //禁用全局请求
    HTTPManager.IsCookiesEnabled = false;
    //删除Cookies
    CookieJar.Clear();

}

Proxy

//通过代理服务器发送请求
void Proxy()
{
    HTTPRequest request = new HTTPRequest(new Uri("request"));
    request.Proxy = new HTTPProxy(new Uri("http://localhost:3128"));
}

Download Progress Tracking

//使用HTTPRequest类的OnProgress事件，跟踪下载进度
void DownloadProgressTracking()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => { });
    request.OnProgress = OnDownloadProgress;
    request.Send();
}

void OnDownloadProgress(HTTPRequest request, int downloaded, int length)
{
    float progressPercent = (downloaded / (float)length) * 100.0f;
    Debug.Log("Downloaded: " + progressPercent.ToString("F2") + "%");
}

Aborting a Request

//终止一个请求
void AbortingRequest()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => { });
    request.Send();

    //调用Abort即终止请求
    request.Abort();
}

Timeouts

//可以设置两种超时时间
void Timeouts()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => { });
    //控制等待客户端和服务端建立连接的时间，默认20s
    request.ConnectTimeout = TimeSpan.FromSeconds(2);
    //设置等待请求处理的时间
    request.Timeout = TimeSpan.FromSeconds(10);
    request.Send();
}

Request States

所有请求都有一个包含它的内部状态的State属性
可能的状态如下：
    Initial：请求的初始状态。这种状态不会被调用
    Queued：等待队列中的待处理。这种状态不会被调用
    Processing：开始处理请求。在这种状态下，客户端将发送请求并解析响应。这种状态不会被调用
    Finished：请求完成没有问题。解析完成的响应，可以使用结果。用户定义的回调将使用有效的响应对象进行调用。请求的Exception属性将为空
    Error：请求在插件中发生意外错误。用户定义的回调将使用空响应对象进行调用。请求的Exception属性可能包含有关该错误的更多信息，但它可以为null
    Aborted：由客户端中止的请求（HTTPRequest的Abort（）函数）,用户定义的回调将用空响应来调用。请求的Exception属性将为空
    ConnectionTimedOut：连接到服务器超时。用户定义的回调将用空响应来调用。请求的Exception属性将为空
    TimedOut：在给定时间内请求未完成。用户定义的回调将用空响应来调用。请求的Exception属性将为空
void RequestStates()
{
    string url = "http://besthttp.azurewebsites.net/api/LeaderboardTest?from=0&count=10"; HTTPRequest request = new HTTPRequest(new Uri(url), (req, resp) =>
    {
        switch (req.State)
        {       
            case HTTPRequestStates.Finished:
                Debug.Log("Request Finished Successfully!\n" + resp.DataAsText);
                break;  
            case HTTPRequestStates.Error:
                Debug.LogError("Request Finished with Error! " + (req.Exception != null ? (req.Exception.Message + "\n" + req.Exception.StackTrace) : "No Exception"));
                break;
            case HTTPRequestStates.Aborted:
                Debug.LogWarning("Request Aborted!");
                break;
            case HTTPRequestStates.ConnectionTimedOut:
                Debug.LogError("Connection Timed Out!");
                break; 
            case HTTPRequestStates.TimedOut:
                Debug.LogError("Processing the request Timed Out!");
                break;
        }
    });

    // Very little time, for testing purposes:
    //request.ConnectTimeout = TimeSpan.FromMilliseconds(2); 
    request.Timeout = TimeSpan.FromSeconds(5);
    request.DisableCache = true;
    request.Send();
}

Request Priority

//通过HTTPRequest对象的Priority属性设置优先级
void RequestPriority()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => { });
    request.Priority = -1;
    request.Send();
}

Server Certificate Validation （服务器证书验证）

//实现ICertificateVerifyer接口并将其设置为HTTPRequest的CustomCertificateVerifyer，可以验证服务器发送的证书：
//using Org.BouncyCastle.Crypto.Tls;
//using Org.BouncyCastle.Asn1.X509;
class CustomVerifier : ICertificateVerifyer
{
    public bool IsValid(Uri targetUri, X509CertificateStructure[] certs)
    {
        // TODO: 若验证失败，返回false      
        return true;  
    }
}

void ServerCertificateValidation()
{
    HTTPRequest request = new HTTPRequest(new Uri("address"), (req, resp) => { });
    request.CustomCertificateVerifyer = new CustomVerifier();
    //使用Bouncy Castle的代码来处理安全协议，而不是Mono的
    request.UseAlternateSSL = true;
    request.Send();
}

Control Redirections（重定向）

//重定向和请求转发
//请求转发：就是服务器内部把对一个request/response的处理权，移交给另外一个 ,它是服务器行为
//重定向:其实是两次request,第一次，客户端request A, 服务器响应，并response回来，告诉浏览器，你应该去B，它是客户端行为
void ControlRedirections()
{
    //需要在主线程以外的线程调用
    HTTPRequest request = new HTTPRequest(new Uri("address"), HTTPMethods.Post);
    request.AddField("field", "data");
    request.OnBeforeRedirection += OnBeforeRedirect;
    request.Send();
}

bool OnBeforeRedirect(HTTPRequest req,HTTPResponse resp,Uri redirectUri)
{
    if(req.MethodType == HTTPMethods.Post&& resp.StatusCode == 302)
    {
        req.MethodType = HTTPMethods.Get;
        //不要发送多余的数据，已经处理的表单数据就清理掉
        req.Clear();
    }
    return true;
}

Statistics(统计)(命名空间)

可以使用HTTPManager.GetGeneralStatistics函数获得有关底层插件的统计信息：
可以查询三种类型的统计信息：

Connections：将返回基于连接的统计信息。如下：
RequestsInQueue：请求队列中正在等待空闲连接的请求数。
Connections：由插件跟踪的HTTPConnection实例的数量。这是所有以下连接的总和。
    ActiveConnections：活动连接的数量。这些连接正在处理请求。
    FreeConnections：可用连接数。这些连接完成一个请求，他们正在等待另一个请求或回收。
    RecycledConnections：回收连接数。这些连接将尽快删除。

Cache：基于缓存的统计。如下：
CacheEntityCount：缓存的响应数
CacheSize：缓存的响应的总和大小。

Cookie：基于Cookie的统计。如下：
CookieCount：Cookie Jar中的Cookie数量。
CookieJarSize：Cookie Jar中Cookie的总和大小。
void Statistics()
{
    GeneralStatistics stats = HTTPManager.GetGeneralStatistics(StatisticsQueryFlags.All);
    Debug.Log(stats.ActiveConnections);
}

Global Settings

通过下面的属性，能更改一些默认值，他们都是节省时间的捷径，这些更改将影响其值更改后创建的所有请求。
可以通过HTTPManager的静态属性修改这些默认值

MaxConnectionPerServer：允许连接到唯一主机的连接数,默认值是4。 http://example.org和https://example.org会被视为两个独立的服务器
KeepAliveDefaultValue：HTTPRequest的IsKeepAlive属性的默认值。
    如果IsKeepAlive为false，到服务器的tcp连接将在每个请求之前设置并在其后立即关闭。如果连续请求很少，它应该更改为false。
    赋给HTTPRequest构造函数的值，将仅针对此请求覆盖此值。默认值是true。
IsCachingDisabled：通过此属性，我们可以全局禁用或启用缓存服务。
    赋给HTTPRequest构造函数的值,将仅针对此请求覆盖此值。默认值是true。
MaxConnectionIdleTime：指定BestHTTP在完成最后一次请求后，销毁连接之前，应该等待的空闲时间。默认值是2分钟。
IsCookiesEnabled：使用此选项，可以启用或禁用所有Cookie操作。默认值是true
CookieJarSize：使用此选项可以控制Cookie存储的大小。默认值是10485760（10 MB）
EnablePrivateBrowsing：如果启用此选项，则不会将Cookie写入磁盘。默认值是false
ConnectTimeout：使用此选项，您可以设置HTTPRequests的默认ConnectTimeout值,默认值是20秒
RequestTimeout：使用此选项，您可以设置HTTPRequests的默认超时值。默认值是60秒
RootCacheFolderProvider：默认情况下，插件会将所有缓存和cookie数据保存在Application.persistentDataPath返回的路径下。
    您可以将一个函数分配给此代理以返回自定义根路径以定义新路径。这个委托将在非Unity线程上被调用！
Proxy：所有HTTP请求的全局默认代理。 HTTPRequest的代理服务器仍然可以根据请求进行更改。默认值为空。
Logger：一种ILogger实现，能够控制将记录关于插件内部的信息，以及如何记录这些信息。
DefaultCertificateVerifyer：可以将ICertificateVerifyer实现设置为此属性。
    在此之后创建的所有新请求将在使用安全协议并且请求的UseAlternateSSL为true时使用此验证器。可以使用ICertificateVerifyer实现来实现服务器证书验证
UseAlternateSSLDefaultValue：通过此属性可以更改HTTPRequest的UseAlternateSSL的默认值

Thread Safety

    由于插件在内部使用线程并行处理所有请求，因此所有共享资源（缓存，cookie等）都是设计和实现线程安全的
一些需要注意的事项：
    调用请求的回调函数以及所有其他回调函数（如WebSocket的回调函数）都是在Unity的主线程上进行的（比如Unity的事件：唤醒，启动，更新等），所以你不需要必须做任何线程同步
    在多个线程上创建，发送请求也是安全的，但您应该调用BestHTTP.HTTPManager.Setup（）; 函数在发送来自Unity事件之一的任何请求之前（例如唤醒，启动）。