Ссылка CFError

Объект CFError инкапсулирует более богатую и расширяемую информацию об ошибке, чем возможное использование только код ошибки или строка ошибки. Базовые атрибуты объекта CFError являются ошибочным доменом (представленный строкой), проблемно-ориентированный код ошибки и “пользовательский информационный словарь”, содержащий специализированную информацию. Ошибки требуются, чтобы иметь домен и код ошибки в том домене. Несколько известных доменов определяются, соответствуя Маху, POSIX и ошибкам OSStatus.

Дополнительный “пользовательский информационный словарь” может предоставить дополнительную информацию, которая могла бы быть полезна для интерпретации и создания отчетов ошибки, включая человекочитаемое описание для ошибки. “Пользовательский информационный словарь” иногда включает другой объект CFError, представляющий ошибку в подсистеме, лежащей в основе ошибки, представленной содержанием объекта CFError. Этот базовый ошибочный объект может предоставить более определенную информацию о причине ошибки.

В целом метод должен сигнализировать состояние ошибки путем возврата, например, false или NULL вместо простым присутствием ошибочного объекта. Метод может тогда дополнительно возвратить объект CFError ссылкой для дальнейшего описания ошибки.

CFError бесплатный соединенный мостом к NSError в платформе Основы — для большего количества подробных данных о бесплатном образовании моста, посмотрите Бесплатные Соединенные мостом Типы. NSError имеет некоторые дополнительные инструкции, упрощающие сообщать об ошибках автоматически пользователям и пытаться восстановиться от них. См. Руководство по программированию Обработки ошибок для получения дополнительной информации о NSError программирование инструкций.

Функции

Создание CFError


    
    CFErrorCreate (_: _: _: _:)
    CFErrorCreate

Создает новый объект CFError.

Объявление

Swift

func CFErrorCreate(_ allocator: CFAllocator!, _ domain: CFString!, _ code: CFIndex, _ userInfo: CFDictionary!) -> CFError!

Objective C

CFErrorRef CFErrorCreate ( CFAllocatorRef allocator, CFStringRef domain, CFIndex code, CFDictionaryRef userInfo );

Параметры

`allocator`	Средство выделения для использования для выделения памяти для нового объекта. Передача `NULL` или `kCFAllocatorDefault` использовать текущее средство выделения по умолчанию.
`domain`	CFString, идентифицирующий ошибочный домен. Если эта ссылка `NULL` или иначе не допустимый CFString, поведение не определено.
`code`	CFIndex, идентифицирующий код ошибки. Код интерпретируется в контексте ошибочного домена.
`userInfo`	CFDictionary, создаваемый с `kCFCopyStringDictionaryKeyCallBacks` и `kCFTypeDictionaryValueCallBacks`. Словарь копируется с `CFDictionaryCreateCopy`. Если Вы не хотите userInfo словарь, можно передать `NULL`, когда будет присвоен пустой словарь.

Возвращаемое значение

Новый объект CFError. Владение соблюдает Создать Правило.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    CFErrorCreateWithUserInfoKeysAndValues (_: _: _: _: _: _:)
    CFErrorCreateWithUserInfoKeysAndValues

Создает новый объект CFError использование данного ключи и значения для создания пользовательского информационного словаря.

Объявление

Swift

func CFErrorCreateWithUserInfoKeysAndValues(_ allocator: CFAllocator!, _ domain: CFString!, _ code: CFIndex, _ userInfoKeys: UnsafePointer<UnsafePointer<Void>>, _ userInfoValues: UnsafePointer<UnsafePointer<Void>>, _ numUserInfoValues: CFIndex) -> CFError!

Objective C

CFErrorRef CFErrorCreateWithUserInfoKeysAndValues ( CFAllocatorRef allocator, CFStringRef domain, CFIndex code, const void *const *userInfoKeys, const void *const *userInfoValues, CFIndex numUserInfoValues );

Параметры

`allocator`	Средство выделения для использования для выделения памяти для нового объекта. Передача `NULL` или `kCFAllocatorDefault` использовать текущее средство выделения по умолчанию.
`domain`	CFString, идентифицирующий ошибочный домен. Если эта ссылка `NULL` или иначе не допустимый CFString, поведение не определено.
`code`	CFIndex, идентифицирующий код ошибки. Код интерпретируется в контексте ошибочного домена.
`userInfoKeys`	Массив `numUserInfoValues` Кфстрингс использовал в качестве ключей в создании userInfo словаря. Значение этого параметра может быть `NULL` если `numUserInfoValues` `0`.
`userInfoValues`	Массив `numUserInfoValues` Типы CF, используемые в качестве значений в создании userInfo словаря. Значение этого параметра может быть `NULL` если `numUserInfoValues` `0`.
`numUserInfoValues`	Число ключей и значений в `userInfoKeys` и `userInfoValues` массивы.

Возвращаемое значение

Новый объект CFError. Владение соблюдает Создать Правило.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.

Получение информации об ошибке


    
    CFErrorGetDomain (_:)
    CFErrorGetDomain

Возвращает ошибочный домен для данного CFError.

Объявление

Swift

func CFErrorGetDomain(_ err: CFError!) -> CFString!

Objective C

CFStringRef CFErrorGetDomain ( CFErrorRef err );

Параметры

err

Ошибка исследовать. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Ошибочный домен для err. Владение соблюдает Получить Правило.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    CFErrorGetCode (_:)
    CFErrorGetCode

Возвращает код ошибки для данного CFError.

Объявление

Swift

func CFErrorGetCode(_ err: CFError!) -> CFIndex

Objective C

CFIndex CFErrorGetCode ( CFErrorRef err );

Параметры

err

Ошибка исследовать. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Код ошибки err.

Обсуждение

Обратите внимание на то, что эта функция возвращает код ошибки для указанного CFError, не ошибочный возврат для текущего вызова.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    CFErrorCopyUserInfo (_:)
    CFErrorCopyUserInfo

Возвращает пользовательский информационный словарь для данного CFError.

Объявление

Swift

func CFErrorCopyUserInfo(_ err: CFError!) -> CFDictionary!

Objective C

CFDictionaryRef CFErrorCopyUserInfo ( CFErrorRef err );

Параметры

err

Ошибка исследовать. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Словарь, содержащий те же ключи и значения как в userInfo словаре err создавался с. Возвращает пустой словарь если NULL был предоставлен создать функции. Владение соблюдает Создать Правило.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    CFErrorCopyDescription (_:)
    CFErrorCopyDescription

Возвращает человечески-презентабельное описание для данной ошибки.

Объявление

Swift

func CFErrorCopyDescription(_ err: CFError!) -> CFString!

Objective C

CFStringRef CFErrorCopyDescription ( CFErrorRef err );

Параметры

err

CFError для исследования. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Локализованное, человечески-презентабельное описание err. Эта функция никогда не возвращается NULL. Владение соблюдает Создать Правило.

Обсуждение

Это - полное предложение или два, который говорит, что перестало работать и почему оно перестало работать. Структура описания зависит от подробной информации, предоставленной в пользовательском информационном словаре. Правила для вычислений возвращаемого значения следующие:

Если значение в пользовательском информационном словаре для kCFErrorLocalizedDescriptionKey не NULL, возвраты то значение как есть.
Если значение в пользовательском информационном словаре для kCFErrorLocalizedFailureReasonKey не NULL, генерируйте ошибку от этого.

Описание - что-то как: «Работа не могла быть завершена». + kCFErrorLocalizedFailureReasonKey
Генерируйте максимально хорошую презентабельную пользователем строку от kCFErrorDescriptionKey, домен и код.

Описание - что-то как подобный: «Работа не могла быть завершена. Домен/код Error произошел». или «Работа не могла быть завершена». + kCFErrorDescriptionKey + «(Домен/код Error)»

Бесплатные соединенные мостом экземпляры NSError мог бы обеспечить дополнительные способы поведения для производства строки описания.

Вы не должны зависеть от точного содержания или формата возвращаемой строки, поскольку это могло бы измениться в различных выпусках операционной системы.

При создании CFError необходимо попытаться удостовериться, что возвращаемое значение человечески-презентабельно и локализуется путем обеспечения значения для kCFErrorLocalizedDescriptionKey в пользовательском информационном словаре.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    КФЕРРОРКОПИФЭЙЛУРЕРИСОН (_:)
    КФЕРРОРКОПИФЭЙЛУРЕРИСОН

Возвращает человечески-презентабельную причину отказа данной ошибки.

Объявление

Swift

func CFErrorCopyFailureReason(_ err: CFError!) -> CFString!

Objective C

CFStringRef CFErrorCopyFailureReason ( CFErrorRef err );

Параметры

err

CFError для исследования. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Локализованный, человечески-презентабельный отказ рассуждает для err, или NULL если никакая презентабельная пользователем строка не доступна. Владение соблюдает Создать Правило.

Обсуждение

Причиной отказа является полное предложение, описывающее, почему работа перестала работать. Во многих случаях это будет просто, «потому что» часть описания (но как полное предложение, делающее локализацию проще). Например, описание ошибки «Не могло сохранить файл 'Буква' в папке 'Documents', потому что объем 'MyDisk' не имеет достаточного количества пространства». мог бы иметь соответствующую причину отказа, «Объем 'MyDisk' не имеет достаточного количества пространства».

По умолчанию эта функция ищет значение для kCFErrorLocalizedFailureReasonKey введите пользовательский информационный словарь. Бесплатные соединенные мостом экземпляры NSError мог бы обеспечить дополнительные способы поведения для производства этого значения.

При создании CFError необходимо попытаться удостовериться, что возвращаемое значение человечески-презентабельно и локализуется путем обеспечения значения для kCFErrorLocalizedFailureReasonKey в пользовательском информационном словаре.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.


    
    CFErrorCopyRecoverySuggestion (_:)
    CFErrorCopyRecoverySuggestion

Возвращает человеческое презентабельное предложение восстановления для данной ошибки.

Объявление

Swift

func CFErrorCopyRecoverySuggestion(_ err: CFError!) -> CFString!

Objective C

CFStringRef CFErrorCopyRecoverySuggestion ( CFErrorRef err );

Параметры

err

CFError для исследования. Если это не допустимый CFError, поведение не определено.

Возвращаемое значение

Локализованное, человечески-презентабельное предложение восстановления для err, или NULL если никакая презентабельная пользователем строка не доступна. Владение соблюдает Создать Правило.

Обсуждение

Это - строка, которая может быть выведена на экран как «информативное» (или «вторичная») сообщение на предупредительной панели. Например, описание ошибки “Не могло сохранить файл 'Буква' в папке 'Documents', потому что объем ‘MyDisk’ не имеет достаточного количества пространства “. мог бы иметь соответствующее предложение восстановления, “Удалите некоторые файлы из объема и попробуйте еще раз “.

По умолчанию эта функция ищет значение для kCFErrorLocalizedRecoverySuggestionKey введите пользовательский информационный словарь. Бесплатные соединенные мостом экземпляры NSError мог бы обеспечить дополнительные способы поведения для производства этого значения.

При создании CFError необходимо попытаться удостовериться, что возвращаемое значение человечески-презентабельно и локализуется путем обеспечения значения для kCFErrorLocalizedRecoverySuggestionKey в пользовательском информационном словаре.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.

Получение идентификатора типа CFError

CFErrorGetTypeID () CFErrorGetTypeID

Возвращает идентификатор типа для непрозрачного типа CFError.

Объявление

Swift

func CFErrorGetTypeID() -> CFTypeID

Objective C

CFTypeID CFErrorGetTypeID ( void );

Возвращаемое значение

Идентификатор типа для непрозрачного типа CFError.

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.

Типы данных

Прочие условия

CFErrorRef CFErrorRef

Ссылка на объект CFError.

Объявление

Swift

typealias CFErrorRef = CFError

Objective C

typedef struct __CFError * CFErrorRef;

Оператор импорта

Objective C

@import CoreFoundation;

Swift

import CoreFoundation

Доступность

Доступный в OS X v10.5 и позже.

Константы

Ошибочные домены
Эти константы определяют домены для объектов CFError.

Объявление

Swift

let kCFErrorDomainPOSIX: CFString! let kCFErrorDomainOSStatus: CFString! let kCFErrorDomainMach: CFString! let kCFErrorDomainCocoa: CFString!

Objective C

const CFStringRef kCFErrorDomainPOSIX; const CFStringRef kCFErrorDomainOSStatus; const CFStringRef kCFErrorDomainMach; const CFStringRef kCFErrorDomainCocoa;

Константы
- kCFErrorDomainPOSIX
  
  kCFErrorDomainPOSIX
  
  Константа, указавшая домен POSIX.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorDomainOSStatus
  
  kCFErrorDomainOSStatus
  
  Константа, указавшая домен OS.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorDomainMach
  
  kCFErrorDomainMach
  
  Константа, указавшая домен Маха.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorDomainCocoa
  
  kCFErrorDomainCocoa
  
  Константа, указавшая домен Cocoa.
  
  Доступный в OS X v10.5 и позже.
Обсуждение

Значение «кода» будет соответствовать существующим ранее значениям в этих доменах.

Доступность

Доступный в OS X v10.5 и позже.
Ключи для пользовательского информационного словаря
Ключи userInfo словарь.

Объявление

Swift

let kCFErrorLocalizedDescriptionKey: CFString! let kCFErrorLocalizedFailureReasonKey: CFString! let kCFErrorLocalizedRecoverySuggestionKey: CFString! let kCFErrorDescriptionKey: CFString! let kCFErrorUnderlyingErrorKey: CFString! let kCFErrorURLKey: CFString! let kCFErrorFilePathKey: CFString!

Objective C

const CFStringRef kCFErrorLocalizedDescriptionKey; const CFStringRef kCFErrorLocalizedFailureReasonKey; const CFStringRef kCFErrorLocalizedRecoverySuggestionKey; const CFStringRef kCFErrorDescriptionKey; const CFStringRef kCFErrorUnderlyingErrorKey; const CFStringRef kCFErrorURLKey; const CFStringRef kCFErrorFilePathKey;

Константы
- kCFErrorLocalizedDescriptionKey
  
  kCFErrorLocalizedDescriptionKey
  
  Ключ для идентификации презентабельного конечным пользователем описания в userInfo словарь.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorLocalizedFailureReasonKey
  
  kCFErrorLocalizedFailureReasonKey
  
  Ключ для идентификации презентабельной конечным пользователем причины отказа в userInfo словарь.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorLocalizedRecoverySuggestionKey
  
  kCFErrorLocalizedRecoverySuggestionKey
  
  Ключ для идентификации презентабельного конечным пользователем предложения восстановления в userInfo словарь.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorDescriptionKey
  
  kCFErrorDescriptionKey
  
  Ключ для идентификации описания в userInfo словарь.
  
  Если у Вас нет локализуемых строк ошибки, при создании объекта CFError можно обеспечить значение для этого ключа. Описание должно быть полным предложением, если это возможно, и не должно содержать доменное имя или код ошибки.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorUnderlyingErrorKey
  
  kCFErrorUnderlyingErrorKey
  
  Ключ для идентификации базовой ошибки в userInfo словарь.
  
  Доступный в OS X v10.5 и позже.
- kCFErrorURLKey
  
  kCFErrorURLKey
  
  Ключ для идентификации связанного URL в userInfo словарь.
  
  Доступный в OS X v10.7 и позже.
- kCFErrorFilePathKey
  
  kCFErrorFilePathKey
  
  Ключ для идентификации связанного пути к файлу в userInfo словарь.
  
  Доступный в OS X v10.7 и позже.
Обсуждение

При создании пользовательского информационного словаря как минимум необходимо обеспечить значения для одного из kCFErrorLocalizedDescriptionKey и kCFErrorLocalizedFailureReasonKey; идеально необходимо обеспечить значения для kCFErrorLocalizedDescriptionKey, kCFErrorLocalizedFailureReasonKey, и kCFErrorLocalizedRecoverySuggestionKey. Как правило, необходимо обеспечить значение для одного из также kCFErrorURLKey или kCFErrorFilePathKey.