/* * @APPLE_LICENSE_HEADER_START@ * * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved. * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* File: HIDInitReport.c Contains: HIDInitReport call for HID Library Version: 1.0d1 Copyright: © 2000 by Apple Computer, Inc., all rights reserved. File Ownership: DRI: David Ferguson Other Contact: Keithen Hayenga Technology: technologies, usb Writers: Change History (most recent first): */ #include "HIDLib.h" /* *------------------------------------------------------------------------------ * * HIDInitReport - Initialize report to have report ID and, if possible, null values * so that setting any one value will not inadvertantly change * other items in the same report to 0. * * Input: * reportType - HIDP_Input, HIDP_Output, HIDP_Feature * reportID - Report ID * preparsedDataRef - Pre-Parsed Data * report - An HID Report * reportLength - The length of the Report * Output: * report - Initialized HID Report * Returns: * *------------------------------------------------------------------------------ */ OSStatus HIDInitReport (HIDReportType reportType, UInt8 reportID, HIDPreparsedDataRef preparsedDataRef, void * report, ByteCount reportLength) { HIDPreparsedDataPtr ptPreparsedData = (HIDPreparsedDataPtr) preparsedDataRef; HIDReportItem * ptReportItem; ByteCount minLength; UInt8 * iPtr; int iR; OSStatus iStatus = kHIDSuccess; //Disallow Null Pointers if ((ptPreparsedData == NULL) || (report == NULL)) return kHIDNullPointerErr; if (ptPreparsedData->hidTypeIfValid != kHIDOSType) return kHIDInvalidPreparsedDataErr; if (reportLength == 0) return kHIDReportSizeZeroErr; // Report length must also be great enough to hold report. HIDGetReportLength(reportType, reportID, &minLength, preparsedDataRef); // I know that HIDGetReportLength repeats the first tests above, but it // was easier to duplicate that logic than build test cases for the other // errors that could be returned by HIDGetReportLength that i don't care // about. if (reportLength < minLength) return kHIDInvalidReportLengthErr; // First byte of report must be reportID. Unless it is report ID 0; // in which case 0 is just the first byte of the following initialization. iPtr = (UInt8 *)report; *iPtr++ = reportID; // Default initialization is to zero out all values. for (iR = 1; iR < reportLength; iR++) { *iPtr++ = 0; } // Search through all report items to see if they belong in this report. for (iR = 0; iR < ptPreparsedData->reportItemCount; iR++) { ptReportItem = &ptPreparsedData->reportItems[iR]; if (ptReportItem->reportType == reportType && ptReportItem->globals.reportID == reportID) { // Is there a null value for this item? SInt32 nullValue; SInt32 bitwiseMax; SInt32 bitwiseMin; SInt32 bitSize; Boolean isSigned; // The HID spec "highly encourages" 0 to be a null value, so test // for it first. if ( 0 < ptReportItem->globals.logicalMinimum || 0 > ptReportItem->globals.logicalMaximum) continue; // Default initialization was good enough. nullValue = 0; // We can test if this changes below. // Determine the maximum and minimum signed numbers that will fit into this // item and then see if they are outside the bounds of what the descriptor // says are the allowed min and max. // What the possible ranges are depends upon if the device is accepting // signed or unsigned numbers. I haven't noticed that information in the // preparsed data, so i'll take an educated guess. If logicalMinimum is // less than 0 it must be using signed numbers. Conversly, logicalMaximum // using the high order bit of it's bitfield would indicate unsigned. In // case of a tie, we'll say signed since that agrees with the SInt32 that // logicalMinimum and logicalMaximum are stored in. // The mininimum 8 bit value would be 0x80 (-128). To be -128 in UInt32 = 0xFFFFFF80. // This just happens to also set the high order bit that we need to test in the // maximum value using the high order bit, such as 64, 0x80. bitSize = ptReportItem->globals.reportSize; bitwiseMin = -1 << (bitSize - 1); // Logical max should not have any bit set higher than the high order bit of our // size, so anding with 0xFFFFFF80 should only test field's high order bit. isSigned = (ptReportItem->globals.logicalMinimum < 0) || !(ptReportItem->globals.logicalMaximum & bitwiseMin); // If signed, we test from 0x80 to 0x7F. If not, 0x00 to 0xFF. if (isSigned) { --bitSize; // Don't let max value flow into sign bit. } else { bitwiseMin = 0; } // Our compare uses SInt32, so even for unsigned values, we can't let them // overflow into real sign bit. (So 0x80000000 is not a legal HID positive number.) if (bitSize >= 32) bitSize = 31; // The theory behind this greatly simplified set of compares. 1. I was worried about // the case of a 4 bit field with a max = 4 and a min = -2. Then if i chose a value // of 7 for my bitwise max, it could also be -1 for min, which would make it a null // positive value, but a legal negative one. But while HID specs say a field can be // either a signed or unsigned value, i don't see how it can be both, so i haven't // allowed for such a situation. 2. I originally built logic that tested for signed // or unsigned fields as above, but had seperate logic based on what would happen // after that. I have resolved that logic down to the main part below and the only // exceptions i had are now filtered out into the 2 lines of "if (signed)" etc. above. bitwiseMax = (1<<bitSize) - 1; if (bitwiseMax > ptReportItem->globals.logicalMaximum) { nullValue = bitwiseMax; } else { if (bitwiseMin < ptReportItem->globals.logicalMinimum) { nullValue = bitwiseMin; } } // If we found a null value, store it into the proper place in the report. if (nullValue != 0) { // Write out the data. SInt32 iStart; int lR; OSStatus tempStatus; HIDPreProcessRIValue(ptReportItem, &nullValue); // For a reportItem, there can be multiple identical usages. for (lR = 0; lR < ptReportItem->usageItemCount; lR++) { iStart = ptReportItem->startBit + (ptReportItem->globals.reportSize * lR); tempStatus = HIDPutData(report, reportLength, iStart, ptReportItem->globals.reportSize, nullValue); if (tempStatus) iStatus = tempStatus; // Pass on any bad news. } } } // == reportID } // reportItemCount return iStatus; }