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

objc2_core_foundation/generated/
CFError.rs
