objc2_foundation/generated/
NSCoder.rs

1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6
7use crate::*;
8
9/// Describes the action an NSCoder should take when it encounters decode failures (e.g. corrupt data) for non-TopLevel decodes.
10///
11/// See also [Apple's documentation](https://developer.apple.com/documentation/foundation/nsdecodingfailurepolicy?language=objc)
12// NS_ENUM
13#[repr(transparent)]
14#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
15pub struct NSDecodingFailurePolicy(pub NSInteger);
16impl NSDecodingFailurePolicy {
17    #[doc(alias = "NSDecodingFailurePolicyRaiseException")]
18    pub const RaiseException: Self = Self(0);
19    #[doc(alias = "NSDecodingFailurePolicySetErrorAndReturn")]
20    pub const SetErrorAndReturn: Self = Self(1);
21}
22
23unsafe impl Encode for NSDecodingFailurePolicy {
24    const ENCODING: Encoding = NSInteger::ENCODING;
25}
26
27unsafe impl RefEncode for NSDecodingFailurePolicy {
28    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
29}
30
31extern_class!(
32    /// [Apple's documentation](https://developer.apple.com/documentation/foundation/nscoder?language=objc)
33    #[unsafe(super(NSObject))]
34    #[derive(Debug, PartialEq, Eq, Hash)]
35    pub struct NSCoder;
36);
37
38unsafe impl NSObjectProtocol for NSCoder {}
39
40impl NSCoder {
41    extern_methods!(
42        #[unsafe(method(encodeValueOfObjCType:at:))]
43        #[unsafe(method_family = none)]
44        pub unsafe fn encodeValueOfObjCType_at(
45            &self,
46            r#type: NonNull<c_char>,
47            addr: NonNull<c_void>,
48        );
49
50        #[cfg(feature = "NSData")]
51        #[unsafe(method(encodeDataObject:))]
52        #[unsafe(method_family = none)]
53        pub unsafe fn encodeDataObject(&self, data: &NSData);
54
55        #[cfg(feature = "NSData")]
56        #[unsafe(method(decodeDataObject))]
57        #[unsafe(method_family = none)]
58        pub unsafe fn decodeDataObject(&self) -> Option<Retained<NSData>>;
59
60        #[unsafe(method(decodeValueOfObjCType:at:size:))]
61        #[unsafe(method_family = none)]
62        pub unsafe fn decodeValueOfObjCType_at_size(
63            &self,
64            r#type: NonNull<c_char>,
65            data: NonNull<c_void>,
66            size: NSUInteger,
67        );
68
69        #[cfg(feature = "NSString")]
70        #[unsafe(method(versionForClassName:))]
71        #[unsafe(method_family = none)]
72        pub unsafe fn versionForClassName(&self, class_name: &NSString) -> NSInteger;
73    );
74}
75
76/// Methods declared on superclass `NSObject`.
77impl NSCoder {
78    extern_methods!(
79        #[unsafe(method(init))]
80        #[unsafe(method_family = init)]
81        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
82
83        #[unsafe(method(new))]
84        #[unsafe(method_family = new)]
85        pub unsafe fn new() -> Retained<Self>;
86    );
87}
88
89/// NSExtendedCoder.
90impl NSCoder {
91    extern_methods!(
92        #[unsafe(method(encodeObject:))]
93        #[unsafe(method_family = none)]
94        pub unsafe fn encodeObject(&self, object: Option<&AnyObject>);
95
96        #[unsafe(method(encodeRootObject:))]
97        #[unsafe(method_family = none)]
98        pub unsafe fn encodeRootObject(&self, root_object: &AnyObject);
99
100        #[unsafe(method(encodeBycopyObject:))]
101        #[unsafe(method_family = none)]
102        pub unsafe fn encodeBycopyObject(&self, an_object: Option<&AnyObject>);
103
104        #[unsafe(method(encodeByrefObject:))]
105        #[unsafe(method_family = none)]
106        pub unsafe fn encodeByrefObject(&self, an_object: Option<&AnyObject>);
107
108        #[unsafe(method(encodeConditionalObject:))]
109        #[unsafe(method_family = none)]
110        pub unsafe fn encodeConditionalObject(&self, object: Option<&AnyObject>);
111
112        #[unsafe(method(encodeArrayOfObjCType:count:at:))]
113        #[unsafe(method_family = none)]
114        pub unsafe fn encodeArrayOfObjCType_count_at(
115            &self,
116            r#type: NonNull<c_char>,
117            count: NSUInteger,
118            array: NonNull<c_void>,
119        );
120
121        #[unsafe(method(encodeBytes:length:))]
122        #[unsafe(method_family = none)]
123        pub unsafe fn encodeBytes_length(&self, byteaddr: *const c_void, length: NSUInteger);
124
125        #[unsafe(method(decodeObject))]
126        #[unsafe(method_family = none)]
127        pub unsafe fn decodeObject(&self) -> Option<Retained<AnyObject>>;
128
129        #[cfg(feature = "NSError")]
130        #[unsafe(method(decodeTopLevelObjectAndReturnError:_))]
131        #[unsafe(method_family = none)]
132        pub unsafe fn decodeTopLevelObjectAndReturnError(
133            &self,
134        ) -> Result<Retained<AnyObject>, Retained<NSError>>;
135
136        #[unsafe(method(decodeArrayOfObjCType:count:at:))]
137        #[unsafe(method_family = none)]
138        pub unsafe fn decodeArrayOfObjCType_count_at(
139            &self,
140            item_type: NonNull<c_char>,
141            count: NSUInteger,
142            array: NonNull<c_void>,
143        );
144
145        #[unsafe(method(decodeBytesWithReturnedLength:))]
146        #[unsafe(method_family = none)]
147        pub unsafe fn decodeBytesWithReturnedLength(
148            &self,
149            lengthp: NonNull<NSUInteger>,
150        ) -> *mut c_void;
151
152        #[unsafe(method(encodePropertyList:))]
153        #[unsafe(method_family = none)]
154        pub unsafe fn encodePropertyList(&self, a_property_list: &AnyObject);
155
156        #[unsafe(method(decodePropertyList))]
157        #[unsafe(method_family = none)]
158        pub unsafe fn decodePropertyList(&self) -> Option<Retained<AnyObject>>;
159
160        #[cfg(feature = "NSZone")]
161        #[unsafe(method(setObjectZone:))]
162        #[unsafe(method_family = none)]
163        pub unsafe fn setObjectZone(&self, zone: *mut NSZone);
164
165        #[cfg(feature = "NSZone")]
166        #[unsafe(method(objectZone))]
167        #[unsafe(method_family = none)]
168        pub unsafe fn objectZone(&self) -> *mut NSZone;
169
170        #[unsafe(method(systemVersion))]
171        #[unsafe(method_family = none)]
172        pub unsafe fn systemVersion(&self) -> c_uint;
173
174        #[unsafe(method(allowsKeyedCoding))]
175        #[unsafe(method_family = none)]
176        pub unsafe fn allowsKeyedCoding(&self) -> bool;
177
178        #[cfg(feature = "NSString")]
179        #[unsafe(method(encodeObject:forKey:))]
180        #[unsafe(method_family = none)]
181        pub unsafe fn encodeObject_forKey(&self, object: Option<&AnyObject>, key: &NSString);
182
183        #[cfg(feature = "NSString")]
184        #[unsafe(method(encodeConditionalObject:forKey:))]
185        #[unsafe(method_family = none)]
186        pub unsafe fn encodeConditionalObject_forKey(
187            &self,
188            object: Option<&AnyObject>,
189            key: &NSString,
190        );
191
192        #[cfg(feature = "NSString")]
193        #[unsafe(method(encodeBool:forKey:))]
194        #[unsafe(method_family = none)]
195        pub unsafe fn encodeBool_forKey(&self, value: bool, key: &NSString);
196
197        #[cfg(feature = "NSString")]
198        #[unsafe(method(encodeInt:forKey:))]
199        #[unsafe(method_family = none)]
200        pub unsafe fn encodeInt_forKey(&self, value: c_int, key: &NSString);
201
202        #[cfg(feature = "NSString")]
203        #[unsafe(method(encodeInt32:forKey:))]
204        #[unsafe(method_family = none)]
205        pub unsafe fn encodeInt32_forKey(&self, value: i32, key: &NSString);
206
207        #[cfg(feature = "NSString")]
208        #[unsafe(method(encodeInt64:forKey:))]
209        #[unsafe(method_family = none)]
210        pub unsafe fn encodeInt64_forKey(&self, value: i64, key: &NSString);
211
212        #[cfg(feature = "NSString")]
213        #[unsafe(method(encodeFloat:forKey:))]
214        #[unsafe(method_family = none)]
215        pub unsafe fn encodeFloat_forKey(&self, value: c_float, key: &NSString);
216
217        #[cfg(feature = "NSString")]
218        #[unsafe(method(encodeDouble:forKey:))]
219        #[unsafe(method_family = none)]
220        pub unsafe fn encodeDouble_forKey(&self, value: c_double, key: &NSString);
221
222        #[cfg(feature = "NSString")]
223        #[unsafe(method(encodeBytes:length:forKey:))]
224        #[unsafe(method_family = none)]
225        pub unsafe fn encodeBytes_length_forKey(
226            &self,
227            bytes: *const u8,
228            length: NSUInteger,
229            key: &NSString,
230        );
231
232        #[cfg(feature = "NSString")]
233        #[unsafe(method(containsValueForKey:))]
234        #[unsafe(method_family = none)]
235        pub unsafe fn containsValueForKey(&self, key: &NSString) -> bool;
236
237        #[cfg(feature = "NSString")]
238        #[unsafe(method(decodeObjectForKey:))]
239        #[unsafe(method_family = none)]
240        pub unsafe fn decodeObjectForKey(&self, key: &NSString) -> Option<Retained<AnyObject>>;
241
242        #[cfg(all(feature = "NSError", feature = "NSString"))]
243        #[unsafe(method(decodeTopLevelObjectForKey:error:_))]
244        #[unsafe(method_family = none)]
245        pub unsafe fn decodeTopLevelObjectForKey_error(
246            &self,
247            key: &NSString,
248        ) -> Result<Retained<AnyObject>, Retained<NSError>>;
249
250        #[cfg(feature = "NSString")]
251        #[unsafe(method(decodeBoolForKey:))]
252        #[unsafe(method_family = none)]
253        pub unsafe fn decodeBoolForKey(&self, key: &NSString) -> bool;
254
255        #[cfg(feature = "NSString")]
256        #[unsafe(method(decodeIntForKey:))]
257        #[unsafe(method_family = none)]
258        pub unsafe fn decodeIntForKey(&self, key: &NSString) -> c_int;
259
260        #[cfg(feature = "NSString")]
261        #[unsafe(method(decodeInt32ForKey:))]
262        #[unsafe(method_family = none)]
263        pub unsafe fn decodeInt32ForKey(&self, key: &NSString) -> i32;
264
265        #[cfg(feature = "NSString")]
266        #[unsafe(method(decodeInt64ForKey:))]
267        #[unsafe(method_family = none)]
268        pub unsafe fn decodeInt64ForKey(&self, key: &NSString) -> i64;
269
270        #[cfg(feature = "NSString")]
271        #[unsafe(method(decodeFloatForKey:))]
272        #[unsafe(method_family = none)]
273        pub unsafe fn decodeFloatForKey(&self, key: &NSString) -> c_float;
274
275        #[cfg(feature = "NSString")]
276        #[unsafe(method(decodeDoubleForKey:))]
277        #[unsafe(method_family = none)]
278        pub unsafe fn decodeDoubleForKey(&self, key: &NSString) -> c_double;
279
280        #[cfg(feature = "NSString")]
281        #[unsafe(method(decodeBytesForKey:returnedLength:))]
282        #[unsafe(method_family = none)]
283        pub unsafe fn decodeBytesForKey_returnedLength(
284            &self,
285            key: &NSString,
286            lengthp: *mut NSUInteger,
287        ) -> *const u8;
288
289        #[cfg(feature = "NSString")]
290        #[unsafe(method(encodeInteger:forKey:))]
291        #[unsafe(method_family = none)]
292        pub unsafe fn encodeInteger_forKey(&self, value: NSInteger, key: &NSString);
293
294        #[cfg(feature = "NSString")]
295        #[unsafe(method(decodeIntegerForKey:))]
296        #[unsafe(method_family = none)]
297        pub unsafe fn decodeIntegerForKey(&self, key: &NSString) -> NSInteger;
298
299        #[unsafe(method(requiresSecureCoding))]
300        #[unsafe(method_family = none)]
301        pub unsafe fn requiresSecureCoding(&self) -> bool;
302
303        #[cfg(feature = "NSString")]
304        #[unsafe(method(decodeObjectOfClass:forKey:))]
305        #[unsafe(method_family = none)]
306        pub unsafe fn decodeObjectOfClass_forKey(
307            &self,
308            a_class: &AnyClass,
309            key: &NSString,
310        ) -> Option<Retained<AnyObject>>;
311
312        #[cfg(all(feature = "NSError", feature = "NSString"))]
313        #[unsafe(method(decodeTopLevelObjectOfClass:forKey:error:_))]
314        #[unsafe(method_family = none)]
315        pub unsafe fn decodeTopLevelObjectOfClass_forKey_error(
316            &self,
317            a_class: &AnyClass,
318            key: &NSString,
319        ) -> Result<Retained<AnyObject>, Retained<NSError>>;
320
321        #[cfg(all(feature = "NSArray", feature = "NSString"))]
322        /// Decodes the
323        /// `NSArray`object for the given
324        /// `key,`which should be an
325        /// `NSArray<cls>,`containing the given non-collection class (no nested arrays or arrays of dictionaries, etc) from the coder.
326        ///
327        /// Requires
328        /// `NSSecureCoding`otherwise an exception is thrown and sets the
329        /// `decodingFailurePolicy`to
330        /// `NSDecodingFailurePolicySetErrorAndReturn.`
331        /// Returns
332        /// `nil`if the object for
333        /// `key`is not of the expected types, or cannot be decoded, and sets the
334        /// `error`on the decoder.
335        #[unsafe(method(decodeArrayOfObjectsOfClass:forKey:))]
336        #[unsafe(method_family = none)]
337        pub unsafe fn decodeArrayOfObjectsOfClass_forKey(
338            &self,
339            cls: &AnyClass,
340            key: &NSString,
341        ) -> Option<Retained<NSArray>>;
342
343        #[cfg(all(feature = "NSDictionary", feature = "NSString"))]
344        /// Decodes the
345        /// `NSDictionary`object for the given
346        /// `key,`which should be an
347        /// `NSDictionary<keyCls,objectCls>`, with keys of type given in
348        /// `keyCls`and objects of the given non-collection class
349        /// `objectCls`(no nested dictionaries or other dictionaries contained in the dictionary, etc) from the coder.
350        ///
351        /// Requires
352        /// `NSSecureCoding`otherwise an exception is thrown and sets the
353        /// `decodingFailurePolicy`to
354        /// `NSDecodingFailurePolicySetErrorAndReturn.`
355        /// Returns
356        /// `nil`if the object for
357        /// `key`is not of the expected types, or cannot be decoded, and sets the
358        /// `error`on the decoder.
359        #[unsafe(method(decodeDictionaryWithKeysOfClass:objectsOfClass:forKey:))]
360        #[unsafe(method_family = none)]
361        pub unsafe fn decodeDictionaryWithKeysOfClass_objectsOfClass_forKey(
362            &self,
363            key_cls: &AnyClass,
364            object_cls: &AnyClass,
365            key: &NSString,
366        ) -> Option<Retained<NSDictionary>>;
367
368        #[cfg(all(feature = "NSSet", feature = "NSString"))]
369        #[unsafe(method(decodeObjectOfClasses:forKey:))]
370        #[unsafe(method_family = none)]
371        pub unsafe fn decodeObjectOfClasses_forKey(
372            &self,
373            classes: Option<&NSSet<AnyClass>>,
374            key: &NSString,
375        ) -> Option<Retained<AnyObject>>;
376
377        #[cfg(all(feature = "NSError", feature = "NSSet", feature = "NSString"))]
378        #[unsafe(method(decodeTopLevelObjectOfClasses:forKey:error:_))]
379        #[unsafe(method_family = none)]
380        pub unsafe fn decodeTopLevelObjectOfClasses_forKey_error(
381            &self,
382            classes: Option<&NSSet<AnyClass>>,
383            key: &NSString,
384        ) -> Result<Retained<AnyObject>, Retained<NSError>>;
385
386        #[cfg(all(feature = "NSArray", feature = "NSSet", feature = "NSString"))]
387        /// Decodes the
388        /// `NSArray`object for the given
389        /// `key,`which should be an
390        /// `NSArray,`containing the given non-collection classes (no nested arrays or arrays of dictionaries, etc) from the coder.
391        ///
392        /// Requires
393        /// `NSSecureCoding`otherwise an exception is thrown and sets the
394        /// `decodingFailurePolicy`to
395        /// `NSDecodingFailurePolicySetErrorAndReturn.`
396        /// Returns
397        /// `nil`if the object for
398        /// `key`is not of the expected types, or cannot be decoded, and sets the
399        /// `error`on the decoder.
400        #[unsafe(method(decodeArrayOfObjectsOfClasses:forKey:))]
401        #[unsafe(method_family = none)]
402        pub unsafe fn decodeArrayOfObjectsOfClasses_forKey(
403            &self,
404            classes: &NSSet<AnyClass>,
405            key: &NSString,
406        ) -> Option<Retained<NSArray>>;
407
408        #[cfg(all(feature = "NSDictionary", feature = "NSSet", feature = "NSString"))]
409        /// Decodes the
410        /// `NSDictionary`object for the given
411        /// `key,`which should be an
412        /// `NSDictionary,`with keys of the types given in
413        /// `keyClasses`and objects of the given non-collection classes in
414        /// `objectClasses`(no nested dictionaries or other dictionaries contained in the dictionary, etc) from the given coder.
415        ///
416        /// Requires
417        /// `NSSecureCoding`otherwise an exception is thrown and sets the
418        /// `decodingFailurePolicy`to
419        /// `NSDecodingFailurePolicySetErrorAndReturn.`
420        /// Returns
421        /// `nil`if the object for
422        /// `key`is not of the expected types, or cannot be decoded, and sets the
423        /// `error`on the decoder.
424        #[unsafe(method(decodeDictionaryWithKeysOfClasses:objectsOfClasses:forKey:))]
425        #[unsafe(method_family = none)]
426        pub unsafe fn decodeDictionaryWithKeysOfClasses_objectsOfClasses_forKey(
427            &self,
428            key_classes: &NSSet<AnyClass>,
429            object_classes: &NSSet<AnyClass>,
430            key: &NSString,
431        ) -> Option<Retained<NSDictionary>>;
432
433        #[cfg(feature = "NSString")]
434        #[unsafe(method(decodePropertyListForKey:))]
435        #[unsafe(method_family = none)]
436        pub unsafe fn decodePropertyListForKey(
437            &self,
438            key: &NSString,
439        ) -> Option<Retained<AnyObject>>;
440
441        #[cfg(feature = "NSSet")]
442        #[unsafe(method(allowedClasses))]
443        #[unsafe(method_family = none)]
444        pub unsafe fn allowedClasses(&self) -> Option<Retained<NSSet<AnyClass>>>;
445
446        #[cfg(feature = "NSError")]
447        /// Signals to this coder that the decode has failed.
448        /// Parameter non-nil error that describes the reason why the decode failed
449        ///
450        /// Sets an error on this NSCoder once per TopLevel decode; calling it repeatedly will have no effect until the call stack unwinds to one of the TopLevel decode entry-points.
451        ///
452        /// This method is only meaningful to call for decodes.
453        ///
454        /// Typically, you would want to call this method in your -initWithCoder: implementation when you detect situations like:
455        /// - lack of secure coding
456        /// - corruption of your data
457        /// - domain validation failures
458        ///
459        /// After calling -failWithError: within your -initWithCoder: implementation, you should clean up and return nil as early as possible.
460        ///
461        /// Once an error has been signaled to a decoder, it remains set until it has handed off to the first TopLevel decode invocation above it.  For example, consider the following call graph:
462        /// A    -decodeTopLevelObjectForKey:error:
463        /// B        -initWithCoder:
464        /// C            -decodeObjectForKey:
465        /// D                -initWithCoder:
466        /// E                    -decodeObjectForKey:
467        /// F                        -failWithError:
468        ///
469        /// In this case the error provided in stack-frame F will be returned via the outError in stack-frame A. Furthermore the result object from decodeTopLevelObjectForKey:error: will be nil, regardless of the result of stack-frame B.
470        ///
471        /// NSCoder implementations support two mechanisms for the stack-unwinding from F to A:
472        /// - forced (NSException based)
473        /// - particpatory (error based)
474        ///
475        /// The kind of unwinding you get is determined by the decodingFailurePolicy property of this NSCoder (which defaults to NSDecodingFailurePolicyRaiseException to match historical behavior).
476        #[unsafe(method(failWithError:))]
477        #[unsafe(method_family = none)]
478        pub unsafe fn failWithError(&self, error: &NSError);
479
480        /// Defines the behavior this NSCoder should take on decode failure (i.e. corrupt archive, invalid data, etc.).
481        ///
482        /// The default result of this property is NSDecodingFailurePolicyRaiseException, subclasses can change this to an alternative policy.
483        #[unsafe(method(decodingFailurePolicy))]
484        #[unsafe(method_family = none)]
485        pub unsafe fn decodingFailurePolicy(&self) -> NSDecodingFailurePolicy;
486
487        #[cfg(feature = "NSError")]
488        /// The current error (if there is one) for the current TopLevel decode.
489        ///
490        /// The meaning of this property changes based on the result of the decodingFailurePolicy property:
491        /// For NSDecodingFailurePolicyRaiseException, this property will always be nil.
492        /// For NSDecodingFailurePolicySetErrorAndReturn, this property can be non-nil, and if so, indicates that there was a failure while decoding the archive (specifically its the very first error encountered).
493        ///
494        /// While .error is non-nil, all attempts to decode data from this coder will return a nil/zero-equivalent value.
495        ///
496        /// This error is consumed by a TopLevel decode API (which resets this coder back to a being able to potentially decode data).
497        #[unsafe(method(error))]
498        #[unsafe(method_family = none)]
499        pub unsafe fn error(&self) -> Option<Retained<NSError>>;
500    );
501}
502
503#[deprecated = "Not supported"]
504#[inline]
505pub unsafe extern "C-unwind" fn NXReadNSObjectFromCoder(
506    decoder: &NSCoder,
507) -> Option<Retained<NSObject>> {
508    extern "C-unwind" {
509        fn NXReadNSObjectFromCoder(decoder: &NSCoder) -> *mut NSObject;
510    }
511    let ret = unsafe { NXReadNSObjectFromCoder(decoder) };
512    unsafe { Retained::retain_autoreleased(ret) }
513}
514
515/// NSTypedstreamCompatibility.
516impl NSCoder {
517    extern_methods!(
518        #[deprecated = "Not supported"]
519        #[unsafe(method(encodeNXObject:))]
520        #[unsafe(method_family = none)]
521        pub unsafe fn encodeNXObject(&self, object: &AnyObject);
522
523        #[deprecated = "Not supported"]
524        #[unsafe(method(decodeNXObject))]
525        #[unsafe(method_family = none)]
526        pub unsafe fn decodeNXObject(&self) -> Option<Retained<AnyObject>>;
527    );
528}
529
530/// NSDeprecated.
531impl NSCoder {
532    extern_methods!(
533        #[deprecated]
534        #[unsafe(method(decodeValueOfObjCType:at:))]
535        #[unsafe(method_family = none)]
536        pub unsafe fn decodeValueOfObjCType_at(
537            &self,
538            r#type: NonNull<c_char>,
539            data: NonNull<c_void>,
540        );
541    );
542}
objc2_foundation/generated/NSCoder.rs

objc2_foundation/generated/
NSCoder.rs
