Ingen beskrivning

AWSMTLModel+NSCoding.h 5.4KB

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