MTLModel+NSCoding.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
  1. //
  2. // MTLModel+NSCoding.h
  3. // Mantle
  4. //
  5. // Created by Justin Spahr-Summers on 2013-02-12.
  6. // Copyright (c) 2013 GitHub. All rights reserved.
  7. //
  8. #import "MTLModel.h"
  9. /// Defines how a MTLModel property key should be encoded into an archive.
  10. ///
  11. /// MTLModelEncodingBehaviorExcluded - The property should never be encoded.
  12. /// MTLModelEncodingBehaviorUnconditional - The property should always be
  13. /// encoded.
  14. /// MTLModelEncodingBehaviorConditional - The object should be encoded only
  15. /// if unconditionally encoded elsewhere.
  16. /// This should only be used for object
  17. /// properties.
  18. typedef enum : NSUInteger {
  19. MTLModelEncodingBehaviorExcluded = 0,
  20. MTLModelEncodingBehaviorUnconditional,
  21. MTLModelEncodingBehaviorConditional,
  22. } MTLModelEncodingBehavior;
  23. /// Implements default archiving and unarchiving behaviors for MTLModel.
  24. @interface MTLModel (NSCoding) <NSCoding>
  25. /// Initializes the receiver from an archive.
  26. ///
  27. /// This will decode the original +modelVersion of the archived object, then
  28. /// invoke -decodeValueForKey:withCoder:modelVersion: for each of the receiver's
  29. /// +propertyKeys.
  30. ///
  31. /// Returns an initialized model object, or nil if a decoding error occurred.
  32. - (id)initWithCoder:(NSCoder *)coder;
  33. /// Archives the receiver using the given coder.
  34. ///
  35. /// This will encode the receiver's +modelVersion, then the receiver's properties
  36. /// according to the behaviors specified in +encodingBehaviorsByPropertyKey.
  37. - (void)encodeWithCoder:(NSCoder *)coder;
  38. /// Determines how the +propertyKeys of the class are encoded into an archive.
  39. /// The values of this dictionary should be boxed MTLModelEncodingBehavior
  40. /// values.
  41. ///
  42. /// Any keys not present in the dictionary will be excluded from the archive.
  43. ///
  44. /// Subclasses overriding this method should combine their values with those of
  45. /// `super`.
  46. ///
  47. /// Returns a dictionary mapping the receiver's +propertyKeys to default encoding
  48. /// behaviors. If a property is an object with `weak` semantics, the default
  49. /// behavior is MTLModelEncodingBehaviorConditional; otherwise, the default is
  50. /// MTLModelEncodingBehaviorUnconditional.
  51. + (NSDictionary *)encodingBehaviorsByPropertyKey;
  52. /// Determines the classes that are allowed to be decoded for each of the
  53. /// receiver's properties when using <NSSecureCoding>. The values of this
  54. /// dictionary should be NSArrays of Class objects.
  55. ///
  56. /// If any encodable keys (as determined by +encodingBehaviorsByPropertyKey) are
  57. /// not present in the dictionary, an exception will be thrown during secure
  58. /// encoding or decoding.
  59. ///
  60. /// Subclasses overriding this method should combine their values with those of
  61. /// `super`.
  62. ///
  63. /// Returns a dictionary mapping the receiver's encodable keys (as determined by
  64. /// +encodingBehaviorsByPropertyKey) to default allowed classes, based on the
  65. /// type that each property is declared as. If type of an encodable property
  66. /// cannot be determined (e.g., it is declared as `id`), it will be omitted from
  67. /// the dictionary, and subclasses must provide a valid value to prevent an
  68. /// exception being thrown during encoding/decoding.
  69. + (NSDictionary *)allowedSecureCodingClassesByPropertyKey;
  70. /// Decodes the value of the given property key from an archive.
  71. ///
  72. /// By default, this method looks for a `-decode<Key>WithCoder:modelVersion:`
  73. /// method on the receiver, and invokes it if found.
  74. ///
  75. /// If the custom method is not implemented and `coder` does not require secure
  76. /// coding, `-[NSCoder decodeObjectForKey:]` will be invoked with the given
  77. /// `key`.
  78. ///
  79. /// If the custom method is not implemented and `coder` requires secure coding,
  80. /// `-[NSCoder decodeObjectOfClasses:forKey:]` will be invoked with the
  81. /// information from +allowedSecureCodingClassesByPropertyKey and the given `key`. The
  82. /// receiver must conform to <NSSecureCoding> for this to work correctly.
  83. ///
  84. /// key - The property key to decode the value for. This argument cannot
  85. /// be nil.
  86. /// coder - The NSCoder representing the archive being decoded. This
  87. /// argument cannot be nil.
  88. /// modelVersion - The version of the original model object that was encoded.
  89. ///
  90. /// Returns the decoded and boxed value, or nil if the key was not present.
  91. - (id)decodeValueForKey:(NSString *)key withCoder:(NSCoder *)coder modelVersion:(NSUInteger)modelVersion;
  92. /// The version of this MTLModel subclass.
  93. ///
  94. /// This version number is saved in archives so that later model changes can be
  95. /// made backwards-compatible with old versions.
  96. ///
  97. /// Subclasses should override this method to return a higher version number
  98. /// whenever a breaking change is made to the model.
  99. ///
  100. /// Returns 0.
  101. + (NSUInteger)modelVersion;
  102. @end
  103. /// This method must be overridden to support archives created by older versions
  104. /// of Mantle (before the `MTLModel+NSCoding` interface existed).
  105. @interface MTLModel (OldArchiveSupport)
  106. /// Converts an archived external representation to a dictionary suitable for
  107. /// passing to -initWithDictionary:.
  108. ///
  109. /// externalRepresentation - The decoded external representation of the receiver.
  110. /// fromVersion - The model version at the time the external
  111. /// representation was encoded.
  112. ///
  113. /// Returns nil by default, indicating that conversion failed.
  114. + (NSDictionary *)dictionaryValueFromArchivedExternalRepresentation:(NSDictionary *)externalRepresentation version:(NSUInteger)fromVersion;
  115. @end