libkdd/kcdata/kdd.h

   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
  34 /*!
  35  * @class KCDataType
  36  * A basic abstraction that allows for parsing data provided by kernel chunked
  37  * data library.
  38  *
  39  * @discussion
  40  * Each type object has a name and a method to parse and populate data in memory to
  41  * a dictionary. The dictionary will have keys as NSStrings and values could be NSObject
  42  *
  43  */
  44 @interface KCDataType : NSObject
  45 - (NSMutableDictionary *)parseData:(void *)dataBuffer ofLength:(uint32_t)length;
  46 - (NSString *)name;
  47 @end
  48
  49 /*!
  50  * @function getKCDataTypeForID
  51  *
  52  * @abstract
  53  * Find a type description for give TypeID
  54  *
  55  * @param typeID
  56  * A unsinged int type specified by the KCDATA.
  57  *
  58  * @discussion
  59  * This routine queries the system for a give type. If a known type description is found it will be used to
  60  * initialize a KCDataType object. If no known type is found it assumes the data is uint8_t[].
  61  */
  62 KCDataType * getKCDataTypeForID(uint32_t typeID);
  63
  64 /*!
  65  * @function KCDataTypeNameForID
  66  *
  67  * @abstract
  68  * Get a name for the type.
  69  *
  70  * @param typeID
  71  * A unsinged int type specified by the KCDATA.
  72  *
  73  * @return NSString *
  74  * Returns name of the type. If a type is not found the return
  75  * value will be string object of the passed value.
  76  */
  77 NSString * KCDataTypeNameForID(uint32_t typeID);
  78
  79 /*!
  80  * @function parseKCDataArray
  81  *
  82  * @abstract
  83  * Parse the given KCDATA buffer as an Array of element. The buffer should begin with header
  84  * of type KCDATA_TYPE_ARRAY.
  85  *
  86  * @param dataBuffer
  87  * A pointer in memory where KCDATA is allocated.
  88  *
  89  * @return
  90  * A dictionary with  key specifying name of the type of each elements and value is an Array of data.
  91  *
  92  */
  93
  94 NSMutableDictionary * parseKCDataArray(void * dataBuffer);
  95
  96 /*!
  97  * @function parseKCDataContainer
  98  *
  99  * @abstract
 100  * Parse the given KCDATA buffer as a container and convert each sub structures as fields in a dictionary.
 101  *
 102  * @param dataBuffer
 103  * A pointer in memory where KCDATA is allocated. The data should be pointing to
 104  * kcdata_item_t of type KCDATA_TYPE_CONTAINER_BEGIN
 105  *
 106  * @param bytesParsed
 107  * A pointer to uint32_t field where the routine will save the number of bytes parsed for this container.
 108  *
 109  * @return NSDictionary *
 110  * containing each field and potentially sub containers within the provided container.
 111  *
 112  * @discussion
 113  * This function tries to parse one container. If it encounters sub containers
 114  * they will be parsed and collected within the same dictionary.
 115  * Other data type fields will also be parsed based on their type. The bytesParsed
 116  * param is populated with the number of bytes processed. With this return value the caller can
 117  * advance its buffer_read position as
 118  *   buffer = (kcdata_item_t)((uintptr_t)buffer + bytesParsed); //advance to next KCDATA_HEADER.
 119  * Note: Keep in mind that the next header may be KCDATA_TYPE_BUFFER_END.
 120  *
 121  * A sample usage call can be:
 122  * KCDATA_ITEM_FOREACH(buffer) {
 123  *     if(KCDATA_ITEM_TYPE(buffer) == KCDATA_TYPE_CONTAINER_BEGIN) {
 124  *         uint32_t container_size = 0;
 125  *         NSMutableDictionary *parsedContainer = parseKCDataContainer(buffer, &container_size);
 126  *         NSLog(@"Parsed container has : %@", parsedContainer);
 127  *         buffer = (kcdata_item_t) ((uintptr_t)buffer + container_size);
 128  *         if(KCDATA_ITEM_TYPE(buffer) == KCDATA_TYPE_BUFFER_END)
 129  *             break;
 130  *     }
 131  * }
 132  *
 133  */
 134 NSMutableDictionary * parseKCDataContainer(void * dataBuffer, uint32_t * bytesParsed);
 135
 136 #endif /* _KDD_H_ */