CFNetDiagnostics Reference

Derived from
Framework
Companion 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 and later.
Declared In
CFNetDiagnostics.h

Data Types

CFNetDiagnosticRef

An opaque reference representing a CFNetDiagnostic.

typedef struct __CFNetDiagnostic* CFNetDiagnosticRef;
Availability
  • Available in OS X version 10.4 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 OS X version 10.4 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;
Constants
kCFNetDiagnosticNoErr

No error occurred but there is no status.

Available in OS X v10.4 and later.

Declared in CFNetDiagnostics.h.

kCFNetDiagnosticErr

An error occurred that prevented the call from completing.

Available in OS X v10.4 and later.

Declared in CFNetDiagnostics.h.

kCFNetDiagnosticConnectionUp

The connection appears to be working.

Available in OS X v10.4 and later.

Declared in CFNetDiagnostics.h.

kCFNetDiagnosticConnectionIndeterminate

The status of the connection is not known.

Available in OS X v10.4 and later.

Declared in CFNetDiagnostics.h.

kCFNetDiagnosticConnectionDown

The connection does not appear to be working.

Available in OS X v10.4 and later.

Declared in CFNetDiagnostics.h.

Discussion

Diagnostic status values are returned by CFNetDiagnosticDiagnoseProblemInteractively and CFNetDiagnosticCopyNetworkStatusPassively.

Availability
  • Available in OS X version 10.4 and later.
Declared In
CFNetwork/CFNetDiagnostics.h