1 /* 2 * Copyright (c) 2015 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29 #ifndef _KDD_H_ 30 #define _KDD_H_ 31 32 #import <Foundation/Foundation.h> 33 #import <kcdata.h> 34 35 /*! 36 * @class KCDataType 37 * A basic abstraction that allows for parsing data provided by kernel chunked 38 * data library. 39 * 40 * @discussion 41 * Each type object has a name and a method to parse and populate data in memory to 42 * a dictionary. The dictionary will have keys as NSStrings and values could be NSObject 43 * 44 */ 45 @interface KCDataType : NSObject 46 - (NSDictionary * _Nullable)parseData:(void * _Nonnull)dataBuffer ofLength:(uint32_t)length NS_RETURNS_RETAINED; 47 - (NSString * _Nonnull)name; 48 - (unsigned int)typeID; 49 - (BOOL) shouldMergeData; 50 @end 51 52 /*! 53 * @function getKCDataTypeForID 54 * 55 * @abstract 56 * Find a type description for give TypeID 57 * 58 * @param typeID 59 * A unsinged int type specified by the KCDATA. 60 * 61 * @discussion 62 * This routine queries the system for a give type. If a known type description is found it will be used to 63 * initialize a KCDataType object. If no known type is found it assumes the data is uint8_t[]. 64 */ 65 KCDataType * _Nullable getKCDataTypeForID(uint32_t typeID); 66 67 /*! 68 * @function KCDataTypeNameForID 69 * 70 * @abstract 71 * Get a name for the type. 72 * 73 * @param typeID 74 * A unsinged int type specified by the KCDATA. 75 * 76 * @return NSString * 77 * Returns name of the type. If a type is not found the return 78 * value will be string object of the passed value. 79 */ 80 NSString * _Nonnull KCDataTypeNameForID(uint32_t typeID) NS_RETURNS_NOT_RETAINED; 81 82 /*! 83 * @function parseKCDataArray 84 * 85 * @abstract 86 * Parse the given KCDATA buffer as an Array of element. The buffer should begin with header 87 * of type KCDATA_TYPE_ARRAY. 88 * 89 * @param iter 90 * An iterator into the input buffer 91 * 92 * @param error 93 * Error return. 94 * 95 * @return 96 * A dictionary with key specifying name of the type of each elements and value is an Array of data. 97 * 98 */ 99 100 NSMutableDictionary * _Nullable parseKCDataArray(kcdata_iter_t iter, NSError * _Nullable * _Nullable error) NS_RETURNS_RETAINED; 101 102 /*! 103 * @function parseKCDataContainer 104 * 105 * @abstract 106 * Parse the given KCDATA buffer as a container and convert each sub structures as fields in a dictionary. 107 * 108 * @param iter 109 * A pointer to an iterator into the input buffer. The iterator will be updated 110 * to point at the container end marker. 111 * 112 * @param error 113 * Error return. 114 * 115 * @return NSDictionary * 116 * containing each field and potentially sub containers within the provided container. 117 * 118 * @discussion 119 * This function tries to parse one container. If it encounters sub containers 120 * they will be parsed and collected within the same dictionary. 121 * Other data type fields will also be parsed based on their type. 122 * 123 */ 124 125 NSMutableDictionary * _Nullable parseKCDataContainer(kcdata_iter_t * _Nonnull iter, NSError * _Nullable * _Nullable error) NS_RETURNS_RETAINED; 126 127 /*! 128 * @function parseKCDataBuffer 129 * 130 * @abstract 131 * Parse complete KCDATA buffer into NSMutableDictionary. Depending on the size of buffer and elements 132 * this routine makes allocations for objects and strings. 133 * 134 * @param dataBuffer 135 * A pointer in memory where KCDATA is allocated. The data should be of type 136 * kcdata_item_t and have KCDATA_BUFFER_BEGIN_* tags (see kern_cdata.h) 137 * 138 * @param size 139 * Size of the buffer as provided by kernel api. 140 * 141 * @return NSDictionary * 142 * Dictionary with key:value pairs for each data item. KCDATA_TYPE_ARRAY and KCDATA_TYPE_CONTAINERS will 143 * grouped and recursed as much possible. For unknown types NSData object is returned with "Type_0x123" 144 * as keys. 145 * 146 * @discussion 147 * This function tries to parse KCDATA buffer with known type description. If an error occurs, 148 * NULL is returned, and error (if not NULL) will have the error string. 149 * 150 * Iff the buffer does begin with a known kcdata magic number, the error code 151 * will be KERN_INVALID_VALUE. 152 * 153 */ 154 NSDictionary * _Nullable parseKCDataBuffer(void * _Nonnull dataBuffer, uint32_t size, NSError * _Nullable * _Nullable error) NS_RETURNS_RETAINED; 155 156 157 #endif /* _KDD_H_ */ 158