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
.
Last updated: 2009-05-06