CFNetDiagnostics Reference

Derived from	CFType
Framework	CoreServices
Companion guide	CFNetwork Programming Guide
Declared in	CFNetDiagnostics.h

Overview

The CFNetDiagnostics opaque type allows you to diagnose network-related problems.

Functions by Task

Creating a net diagnostics object

CFNetDiagnostics Functions

Functions

CFNetDiagnosticCopyNetworkStatusPassively

Gets a network status value.

CFNetDiagnosticStatus CFNetDiagnosticCopyNetworkStatusPassively (
   CFNetDiagnosticRef details,
   CFStringRef *description
);

Parameters

details: CFNetDiagnosticRef, created by CFNetDiagnosticCreateWithStreams or CFNetDiagnosticCreateWithURL, for which the Network Diagnostics status is to be obtained.
description: If not NULL, upon return contains a localized string containing a description of the current network status. Ownership follows the Create Rule.

Return Value

A network status value.

Discussion

This function returns a status value that can be used to display basic information about the connection, and optionally gets a localized string containing a description of the current network status.

This function is guaranteed not to generate network activity.

Special Considerations

This function is thread safe as long as another thread does not alter the same CFNetDiagnosticRef at the same time.

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

CFNetDiagnosticCreateWithStreams

Creates a network diagnostic object from a pair of CFStreams.

CFNetDiagnosticRef CFNetDiagnosticCreateWithStreams (
   CFAllocatorRef alloc,
   CFReadStreamRef readStream,
   CFWriteStreamRef writeStream
);

Parameters

alloc: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
readStream: Reference to a read stream whose connection has failed, or NULL if you do not want the CFNetDiagnosticRef to have a read stream.
writeStream: Reference to a write stream whose connection has failed, or NULL if you do not want the CFNetDiagnosticRef to have a write stream.
function result: CFNetDiagnosticRef that you can pass to CFNetDiagnosticDiagnoseProblemInteractively or CFNetDiagnosticCopyNetworkStatusPassively. Ownership follows the Create Rule.

Discussion

This function uses references to a read steam and a write stream (or just a read stream or just a write stream) to create a reference to an instance of a CFNetDiagnostic object. You can pass the reference to CFNetDiagnosticDiagnoseProblemInteractively to open a Network Diagnostics window or to CFNetDiagnosticCopyNetworkStatusPassively to get a description of the connection referenced by readStream and writeStream.

Special Considerations

This function is thread safe as long as another thread does not alter the same CFNetDiagnosticRef at the same time.

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

CFNetDiagnosticCreateWithURL

Creates a CFNetDiagnosticRef from a CFURLRef.

CFNetDiagnosticRef CFNetDiagnosticCreateWithURL (
   CFAllocatorRef alloc,
   CFURLRef url
);

Parameters

alloc: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
url: CFURLRef that refers to the failed connection.

Return Value

CFNetDiagnosticRef that you can pass to CFNetDiagnosticDiagnoseProblemInteractively or CFNetDiagnosticCopyNetworkStatusPassively. Ownership follows the Create Rule.

Discussion

This function uses a URL to create a reference to an instance of a CFNetDiagnostic object. You can pass the reference to CFNetDiagnosticDiagnoseProblemInteractively to open a Network Diagnostics window or to CFNetDiagnosticCopyNetworkStatusPassively to get a description of the connection referenced by readStream and writeStream.

Special Considerations

This function is thread safe as long as another thread does not alter the same CFNetDiagnosticRef at the same time.

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

CFNetDiagnosticDiagnoseProblemInteractively

Opens a Network Diagnostics window.

CFNetDiagnosticStatus CFNetDiagnosticDiagnoseProblemInteractively (
   CFNetDiagnosticRef details
);

Parameters

details: A network diagnostics object, created by CFNetDiagnosticCreateWithStreams or CFNetDiagnosticCreateWithURL, for which the window is to be opened.

Return Value

CFNetDiagnosticNoErr if no error occurred, or CFNetDiagnosticErr if an error occurred that prevented this call from completing successfully.

Discussion

This function opens the Network Diagnostics window and returns immediately once the window is open.

Special Considerations

This function is thread safe as long as another thread does not alter the same CFNetDiagnosticRef at the same time.

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

CFNetDiagnosticSetName

Overrides the displayed application name.

void CFNetDiagnosticSetName (
   CFNetDiagnosticRef details,
   CFStringRef name
);

Parameters

details: The network diagnostics object for which the application name is to be set.
name: Name that is to be set.

Discussion

Frameworks requiring that an application name be displayed to the user derive the application name from the bundle identifier of the currently running application, in that application’s localization. If you want to override the derived application name, use this function to set the name that is displayed.

Special Considerations

This function is thread safe as long as another thread does not alter the same CFNetDiagnosticRef at the same time.

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

Data Types

CFNetDiagnosticRef

An opaque reference representing a CFNetDiagnostic.

typedef struct __CFNetDiagnostic* CFNetDiagnosticRef;

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

CFNetDiagnosticStatus

A CFIndex type that is used to return status values from CFNetDiagnostic status and diagnostic functions. For a list of possible values, see “CFNetDiagnosticStatusValues Constants.”

typedef CFIndex                         CFNetDiagnosticStatus;

Availability

Available in iOS 2.0 and later.

Declared In

CFNetDiagnostics.h

Constants

CFNetDiagnosticStatusValues Constants

Constants for diagnostic status values.

enum CFNetDiagnosticStatusValues {
    kCFNetDiagnosticNoErr = 0,
    kCFNetDiagnosticErr = -66560L,
    kCFNetDiagnosticConnectionUp = -66559L,
    kCFNetDiagnosticConnectionIndeterminate = -66558L,
    kCFNetDiagnosticConnectionDown = -66557L
};
typedef enum CFNetDiagnosticStatusValues CFNetDiagnosticStatusValues;