objc2_core_foundation/generated/
CFError.rs

1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::cell::UnsafeCell;
4use core::ffi::*;
5use core::marker::{PhantomData, PhantomPinned};
6use core::ptr::NonNull;
7#[cfg(feature = "objc2")]
8use objc2::__framework_prelude::*;
9
10use crate::*;
11
12/// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/cferrordomain?language=objc)
13// NS_TYPED_EXTENSIBLE_ENUM
14pub type CFErrorDomain = CFString;
15
16/// This is the type of a reference to CFErrors.  CFErrorRef is toll-free bridged with NSError.
17///
18/// This is toll-free bridged with `NSError`.
19///
20/// See also [Apple's documentation](https://developer.apple.com/documentation/corefoundation/cferror?language=objc)
21#[doc(alias = "CFErrorRef")]
22#[repr(C)]
23pub struct CFError {
24    inner: [u8; 0],
25    _p: UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>,
26}
27
28cf_type!(
29    unsafe impl CFError {}
30);
31#[cfg(feature = "objc2")]
32cf_objc2_type!(
33    unsafe impl RefEncode<"__CFError"> for CFError {}
34);
35
36unsafe impl ConcreteType for CFError {
37    /// Returns the type identifier of all CFError instances.
38    #[doc(alias = "CFErrorGetTypeID")]
39    #[inline]
40    fn type_id() -> CFTypeID {
41        extern "C-unwind" {
42            fn CFErrorGetTypeID() -> CFTypeID;
43        }
44        unsafe { CFErrorGetTypeID() }
45    }
46}
47
48extern "C" {
49    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrordomainposix?language=objc)
50    pub static kCFErrorDomainPOSIX: Option<&'static CFErrorDomain>;
51}
52
53extern "C" {
54    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrordomainosstatus?language=objc)
55    pub static kCFErrorDomainOSStatus: Option<&'static CFErrorDomain>;
56}
57
58extern "C" {
59    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrordomainmach?language=objc)
60    pub static kCFErrorDomainMach: Option<&'static CFErrorDomain>;
61}
62
63extern "C" {
64    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrordomaincocoa?language=objc)
65    pub static kCFErrorDomainCocoa: Option<&'static CFErrorDomain>;
66}
67
68extern "C" {
69    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorlocalizeddescriptionkey?language=objc)
70    pub static kCFErrorLocalizedDescriptionKey: Option<&'static CFString>;
71}
72
73extern "C" {
74    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorlocalizedfailurekey?language=objc)
75    pub static kCFErrorLocalizedFailureKey: Option<&'static CFString>;
76}
77
78extern "C" {
79    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorlocalizedfailurereasonkey?language=objc)
80    pub static kCFErrorLocalizedFailureReasonKey: Option<&'static CFString>;
81}
82
83extern "C" {
84    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorlocalizedrecoverysuggestionkey?language=objc)
85    pub static kCFErrorLocalizedRecoverySuggestionKey: Option<&'static CFString>;
86}
87
88extern "C" {
89    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrordescriptionkey?language=objc)
90    pub static kCFErrorDescriptionKey: Option<&'static CFString>;
91}
92
93extern "C" {
94    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorunderlyingerrorkey?language=objc)
95    pub static kCFErrorUnderlyingErrorKey: Option<&'static CFString>;
96}
97
98extern "C" {
99    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorurlkey?language=objc)
100    pub static kCFErrorURLKey: Option<&'static CFString>;
101}
102
103extern "C" {
104    /// [Apple's documentation](https://developer.apple.com/documentation/corefoundation/kcferrorfilepathkey?language=objc)
105    pub static kCFErrorFilePathKey: Option<&'static CFString>;
106}
107
108impl CFError {
109    /// Creates a new CFError.
110    ///
111    /// Parameter `allocator`: The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the
112    /// current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
113    ///
114    /// Parameter `domain`: A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.
115    ///
116    /// Parameter `code`: A CFIndex identifying the error code. The code is interpreted within the context of the error domain.
117    ///
118    /// Parameter `userInfo`: A CFDictionary created with kCFCopyStringDictionaryKeyCallBacks and kCFTypeDictionaryValueCallBacks. It will be copied with CFDictionaryCreateCopy().
119    /// If no userInfo dictionary is desired, NULL may be passed in as a convenience, in which case an empty userInfo dictionary will be assigned.
120    ///
121    /// Returns: A reference to the new CFError.
122    ///
123    /// # Safety
124    ///
125    /// - `allocator` might not allow `None`.
126    /// - `domain` might not allow `None`.
127    /// - `user_info` generics must be of the correct type.
128    /// - `user_info` might not allow `None`.
129    #[doc(alias = "CFErrorCreate")]
130    #[cfg(feature = "CFDictionary")]
131    #[inline]
132    pub unsafe fn new(
133        allocator: Option<&CFAllocator>,
134        domain: Option<&CFErrorDomain>,
135        code: CFIndex,
136        user_info: Option<&CFDictionary>,
137    ) -> Option<CFRetained<CFError>> {
138        extern "C-unwind" {
139            fn CFErrorCreate(
140                allocator: Option<&CFAllocator>,
141                domain: Option<&CFErrorDomain>,
142                code: CFIndex,
143                user_info: Option<&CFDictionary>,
144            ) -> Option<NonNull<CFError>>;
145        }
146        let ret = unsafe { CFErrorCreate(allocator, domain, code, user_info) };
147        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
148    }
149
150    /// Creates a new CFError without having to create an intermediate userInfo dictionary.
151    ///
152    /// Parameter `allocator`: The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the
153    /// current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
154    ///
155    /// Parameter `domain`: A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.
156    ///
157    /// Parameter `code`: A CFIndex identifying the error code. The code is interpreted within the context of the error domain.
158    ///
159    /// Parameter `userInfoKeys`: An array of numUserInfoValues CFStrings used as keys in creating the userInfo dictionary. NULL is valid only if numUserInfoValues is 0.
160    ///
161    /// Parameter `userInfoValues`: An array of numUserInfoValues CF types used as values in creating the userInfo dictionary.  NULL is valid only if numUserInfoValues is 0.
162    ///
163    /// Parameter `numUserInfoValues`: CFIndex representing the number of keys and values in the userInfoKeys and userInfoValues arrays.
164    ///
165    /// Returns: A reference to the new CFError. numUserInfoValues CF types are gathered from each of userInfoKeys and userInfoValues to create the userInfo dictionary.
166    ///
167    /// # Safety
168    ///
169    /// - `allocator` might not allow `None`.
170    /// - `domain` might not allow `None`.
171    /// - `user_info_keys` must be a valid pointer.
172    /// - `user_info_values` must be a valid pointer.
173    #[doc(alias = "CFErrorCreateWithUserInfoKeysAndValues")]
174    #[inline]
175    pub unsafe fn with_user_info_keys_and_values(
176        allocator: Option<&CFAllocator>,
177        domain: Option<&CFErrorDomain>,
178        code: CFIndex,
179        user_info_keys: *const *const c_void,
180        user_info_values: *const *const c_void,
181        num_user_info_values: CFIndex,
182    ) -> Option<CFRetained<CFError>> {
183        extern "C-unwind" {
184            fn CFErrorCreateWithUserInfoKeysAndValues(
185                allocator: Option<&CFAllocator>,
186                domain: Option<&CFErrorDomain>,
187                code: CFIndex,
188                user_info_keys: *const *const c_void,
189                user_info_values: *const *const c_void,
190                num_user_info_values: CFIndex,
191            ) -> Option<NonNull<CFError>>;
192        }
193        let ret = unsafe {
194            CFErrorCreateWithUserInfoKeysAndValues(
195                allocator,
196                domain,
197                code,
198                user_info_keys,
199                user_info_values,
200                num_user_info_values,
201            )
202        };
203        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
204    }
205
206    /// Returns the error domain the CFError was created with.
207    ///
208    /// Parameter `err`: The CFError whose error domain is to be returned. If this reference is not a valid CFError, the behavior is undefined.
209    ///
210    /// Returns: The error domain of the CFError. Since this is a "Get" function, the caller shouldn't CFRelease the return value.
211    #[doc(alias = "CFErrorGetDomain")]
212    #[inline]
213    pub fn domain(&self) -> Option<CFRetained<CFErrorDomain>> {
214        extern "C-unwind" {
215            fn CFErrorGetDomain(err: &CFError) -> Option<NonNull<CFErrorDomain>>;
216        }
217        let ret = unsafe { CFErrorGetDomain(self) };
218        ret.map(|ret| unsafe { CFRetained::retain(ret) })
219    }
220
221    /// Returns the error code the CFError was created with.
222    ///
223    /// Parameter `err`: The CFError whose error code is to be returned. If this reference is not a valid CFError, the behavior is undefined.
224    ///
225    /// Returns: The error code of the CFError (not an error return for the current call).
226    #[doc(alias = "CFErrorGetCode")]
227    #[inline]
228    pub fn code(&self) -> CFIndex {
229        extern "C-unwind" {
230            fn CFErrorGetCode(err: &CFError) -> CFIndex;
231        }
232        unsafe { CFErrorGetCode(self) }
233    }
234
235    /// Returns CFError userInfo dictionary.
236    ///
237    /// Returns a dictionary containing the same keys and values as in the userInfo dictionary the CFError was created with. Returns an empty dictionary if NULL was supplied to CFErrorCreate().
238    ///
239    /// Parameter `err`: The CFError whose error user info is to be returned. If this reference is not a valid CFError, the behavior is undefined.
240    ///
241    /// Returns: The user info of the CFError.
242    #[doc(alias = "CFErrorCopyUserInfo")]
243    #[cfg(feature = "CFDictionary")]
244    #[inline]
245    pub fn user_info(&self) -> Option<CFRetained<CFDictionary>> {
246        extern "C-unwind" {
247            fn CFErrorCopyUserInfo(err: &CFError) -> Option<NonNull<CFDictionary>>;
248        }
249        let ret = unsafe { CFErrorCopyUserInfo(self) };
250        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
251    }
252
253    /// Returns a human-presentable description for the error. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedDescriptionKey at the time of CFError creation.
254    ///
255    /// This is a complete sentence or two which says what failed and why it failed. Please refer to header comments for -[NSError localizedDescription] for details on the steps used to compute this; but roughly:
256    /// - Use value of kCFErrorLocalizedDescriptionKey as-is if provided.
257    /// - Use value of kCFErrorLocalizedFailureKey if provided, optionally followed by kCFErrorLocalizedFailureReasonKey if available.
258    /// - Use value of kCFErrorLocalizedFailureReasonKey, combining with a generic failure message such as: "Operation code not be completed. " + kCFErrorLocalizedFailureReasonKey.
259    /// - If all of the above fail, generate a semi-user presentable string from kCFErrorDescriptionKey, the domain, and code. Something like: "Operation could not be completed. Error domain/code occurred. " or "Operation could not be completed. " + kCFErrorDescriptionKey + " (Error domain/code)"
260    /// Toll-free bridged NSError instances might provide additional behaviors for manufacturing a description string.  Do not count on the exact contents or format of the returned string, it might change.
261    ///
262    /// Parameter `err`: The CFError whose description is to be returned. If this reference is not a valid CFError, the behavior is undefined.
263    ///
264    /// Returns: A CFString with human-presentable description of the CFError. Never NULL.
265    #[doc(alias = "CFErrorCopyDescription")]
266    #[inline]
267    pub fn description(&self) -> Option<CFRetained<CFString>> {
268        extern "C-unwind" {
269            fn CFErrorCopyDescription(err: &CFError) -> Option<NonNull<CFString>>;
270        }
271        let ret = unsafe { CFErrorCopyDescription(self) };
272        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
273    }
274
275    /// Returns a human-presentable failure reason for the error.  May return NULL.  CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedFailureReasonKey at the time of CFError creation.
276    ///
277    /// This is a complete sentence which describes why the operation failed. In many cases this will be just the "because" part of the description (but as a complete sentence, which makes localization easier). By default this looks for kCFErrorLocalizedFailureReasonKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL.
278    /// Example Description: "Could not save file 'Letter' in folder 'Documents' because the volume 'MyDisk' doesn't have enough space."
279    /// Corresponding FailureReason: "The volume 'MyDisk' doesn't have enough space."
280    ///
281    /// Parameter `err`: The CFError whose failure reason is to be returned. If this reference is not a valid CFError, the behavior is undefined.
282    ///
283    /// Returns: A CFString with the localized, end-user presentable failure reason of the CFError, or NULL.
284    #[doc(alias = "CFErrorCopyFailureReason")]
285    #[inline]
286    pub fn failure_reason(&self) -> Option<CFRetained<CFString>> {
287        extern "C-unwind" {
288            fn CFErrorCopyFailureReason(err: &CFError) -> Option<NonNull<CFString>>;
289        }
290        let ret = unsafe { CFErrorCopyFailureReason(self) };
291        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
292    }
293
294    /// Returns a human presentable recovery suggestion for the error.  May return NULL.  CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedRecoverySuggestionKey at the time of CFError creation.
295    ///
296    /// This is the string that can be displayed as the "informative" (aka "secondary") message on an alert panel. By default this looks for kCFErrorLocalizedRecoverySuggestionKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL.
297    /// Example Description: "Could not save file 'Letter' in folder 'Documents' because the volume 'MyDisk' doesn't have enough space."
298    /// Corresponding RecoverySuggestion: "Remove some files from the volume and try again."
299    ///
300    /// Parameter `err`: The CFError whose recovery suggestion is to be returned. If this reference is not a valid CFError, the behavior is undefined.
301    ///
302    /// Returns: A CFString with the localized, end-user presentable recovery suggestion of the CFError, or NULL.
303    #[doc(alias = "CFErrorCopyRecoverySuggestion")]
304    #[inline]
305    pub fn recovery_suggestion(&self) -> Option<CFRetained<CFString>> {
306        extern "C-unwind" {
307            fn CFErrorCopyRecoverySuggestion(err: &CFError) -> Option<NonNull<CFString>>;
308        }
309        let ret = unsafe { CFErrorCopyRecoverySuggestion(self) };
310        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
311    }
312}
313
314#[cfg(feature = "CFDictionary")]
315#[deprecated = "renamed to `CFError::new`"]
316#[inline]
317pub unsafe extern "C-unwind" fn CFErrorCreate(
318    allocator: Option<&CFAllocator>,
319    domain: Option<&CFErrorDomain>,
320    code: CFIndex,
321    user_info: Option<&CFDictionary>,
322) -> Option<CFRetained<CFError>> {
323    extern "C-unwind" {
324        fn CFErrorCreate(
325            allocator: Option<&CFAllocator>,
326            domain: Option<&CFErrorDomain>,
327            code: CFIndex,
328            user_info: Option<&CFDictionary>,
329        ) -> Option<NonNull<CFError>>;
330    }
331    let ret = unsafe { CFErrorCreate(allocator, domain, code, user_info) };
332    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
333}
334
335#[deprecated = "renamed to `CFError::with_user_info_keys_and_values`"]
336#[inline]
337pub unsafe extern "C-unwind" fn CFErrorCreateWithUserInfoKeysAndValues(
338    allocator: Option<&CFAllocator>,
339    domain: Option<&CFErrorDomain>,
340    code: CFIndex,
341    user_info_keys: *const *const c_void,
342    user_info_values: *const *const c_void,
343    num_user_info_values: CFIndex,
344) -> Option<CFRetained<CFError>> {
345    extern "C-unwind" {
346        fn CFErrorCreateWithUserInfoKeysAndValues(
347            allocator: Option<&CFAllocator>,
348            domain: Option<&CFErrorDomain>,
349            code: CFIndex,
350            user_info_keys: *const *const c_void,
351            user_info_values: *const *const c_void,
352            num_user_info_values: CFIndex,
353        ) -> Option<NonNull<CFError>>;
354    }
355    let ret = unsafe {
356        CFErrorCreateWithUserInfoKeysAndValues(
357            allocator,
358            domain,
359            code,
360            user_info_keys,
361            user_info_values,
362            num_user_info_values,
363        )
364    };
365    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
366}
367
368#[deprecated = "renamed to `CFError::domain`"]
369#[inline]
370pub extern "C-unwind" fn CFErrorGetDomain(err: &CFError) -> Option<CFRetained<CFErrorDomain>> {
371    extern "C-unwind" {
372        fn CFErrorGetDomain(err: &CFError) -> Option<NonNull<CFErrorDomain>>;
373    }
374    let ret = unsafe { CFErrorGetDomain(err) };
375    ret.map(|ret| unsafe { CFRetained::retain(ret) })
376}
377
378#[deprecated = "renamed to `CFError::code`"]
379#[inline]
380pub extern "C-unwind" fn CFErrorGetCode(err: &CFError) -> CFIndex {
381    extern "C-unwind" {
382        fn CFErrorGetCode(err: &CFError) -> CFIndex;
383    }
384    unsafe { CFErrorGetCode(err) }
385}
386
387#[cfg(feature = "CFDictionary")]
388#[deprecated = "renamed to `CFError::user_info`"]
389#[inline]
390pub extern "C-unwind" fn CFErrorCopyUserInfo(err: &CFError) -> Option<CFRetained<CFDictionary>> {
391    extern "C-unwind" {
392        fn CFErrorCopyUserInfo(err: &CFError) -> Option<NonNull<CFDictionary>>;
393    }
394    let ret = unsafe { CFErrorCopyUserInfo(err) };
395    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
396}
397
398#[deprecated = "renamed to `CFError::description`"]
399#[inline]
400pub extern "C-unwind" fn CFErrorCopyDescription(err: &CFError) -> Option<CFRetained<CFString>> {
401    extern "C-unwind" {
402        fn CFErrorCopyDescription(err: &CFError) -> Option<NonNull<CFString>>;
403    }
404    let ret = unsafe { CFErrorCopyDescription(err) };
405    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
406}
407
408#[deprecated = "renamed to `CFError::failure_reason`"]
409#[inline]
410pub extern "C-unwind" fn CFErrorCopyFailureReason(err: &CFError) -> Option<CFRetained<CFString>> {
411    extern "C-unwind" {
412        fn CFErrorCopyFailureReason(err: &CFError) -> Option<NonNull<CFString>>;
413    }
414    let ret = unsafe { CFErrorCopyFailureReason(err) };
415    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
416}
417
418#[deprecated = "renamed to `CFError::recovery_suggestion`"]
419#[inline]
420pub extern "C-unwind" fn CFErrorCopyRecoverySuggestion(
421    err: &CFError,
422) -> Option<CFRetained<CFString>> {
423    extern "C-unwind" {
424        fn CFErrorCopyRecoverySuggestion(err: &CFError) -> Option<NonNull<CFString>>;
425    }
426    let ret = unsafe { CFErrorCopyRecoverySuggestion(err) };
427    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
428}
objc2_core_foundation/generated/CFError.rs

objc2_core_foundation/generated/
CFError.rs
