Using Network Diagnostics

@官方文档翻译-李冰

@译文

在很多基于网络的应用程序中，可能会发生于你应用程序无关的基于网络的错误。但是，大多数 用户也许不知道为什么应用程序出错。CFNetDiagnostics API允许你做一点小的工作去以一个快速而简单的方式帮助用户解决他们的网络问题。

如果你的应用程序使用CFStream对象，则可以通过调用CFNetDiagnosticCreateWithStreams函数创建一个网络检测引用(CFNetDiagnosticRef)。CFNetDiagnosticCreateWithStreams需要一个分配器，一个读取流和一个写入流作为参数。如果你的应用程序只使用了读取流或写入流，没有用到的参数设置为NULL。

如果没有存在的流你也可以直接用URL创建一个网络检测引用。要这样做，调用CFNetDiagnosticCreateWithURL函数并且传入一个分配器，CFURLRef对象URL。它将返回一个网络检测引用供你使用。

通过Network Diagnostic Assistant诊断问题, 调用 CFNetDiagnosticDiagnoseProblemInteractively函数并传入网络诊断引用. 表 6-1 展示了如何对run loop上的流使用CFNetDiagnostics 。

表 6-1 Using the CFNetDiagnostics API when a stream error occurs

case kCFStreamEventErrorOccurred:
        CFNetDiagnosticRef diagRef =
            CFNetDiagnosticCreateWithStreams(NULL, stream, NULL);
        (void)CFNetDiagnosticDiagnoseProblemInteractively(diagRef);
        CFStreamError error = CFReadStreamGetError(stream);
        reportError(error);
        CFReadStreamClose(stream);
        CFRelease(stream);
        break;

CFNetworkDiagnostics还使您能够检索问题的状态，而不是使用Network Diagnostic Assistant。 这是通过调用CFNetDiagnosticCopyNetworkStatusPassively来实现的，它返回一个常量值，例如kCFNetDiagnosticConnectionUp或kCFNetDiagnosticConnectionIndeterminate。

---

Using Network Diagnostics

官方文档

In many network-based applications, network-based errors may occur that are unrelated to your application. However, most users are probably unaware of why an application is failing. The CFNetDiagnostics API allows you a quick and easy way to help the user fix their network problems with little work on your end.

If your application is using a CFStream object, then create a network diagnostic reference (CFNetDiagnosticRef) by calling the function CFNetDiagnosticCreateWithStreams. CFNetDiagnosticCreateWithStreams takes an allocator, a read stream, and a write stream as arguments. If your application uses only a read stream or a write stream, the unused argument should be set to NULL.

You can also create a network diagnostic reference straight from a URL if no stream exists. To do this, call the CFNetDiagnosticCreateWithURL function and pass it an allocator, and the URL as a CFURLRef. It will return a network diagnostic reference for you to use.

To diagnose the problem through the Network Diagnostic Assistant, call the CFNetDiagnosticDiagnoseProblemInteractively function and pass the network diagnostic reference. Listing 6-1 shows how to use CFNetDiagnostics with streams implemented on a run loop.

Listing 6-1 Using the CFNetDiagnostics API when a stream error occurs

case kCFStreamEventErrorOccurred:
        CFNetDiagnosticRef diagRef =
            CFNetDiagnosticCreateWithStreams(NULL, stream, NULL);
        (void)CFNetDiagnosticDiagnoseProblemInteractively(diagRef);
        CFStreamError error = CFReadStreamGetError(stream);
        reportError(error);
        CFReadStreamClose(stream);
        CFRelease(stream);
        break;

CFNetworkDiagnostics also gives you the ability to retrieve the status of the problem rather than using the Network Diagnostic Assistant. This is accomplished by calling CFNetDiagnosticCopyNetworkStatusPassively, which returns a constant value such as kCFNetDiagnosticConnectionUp or kCFNetDiagnosticConnectionIndeterminate.