/********************************************************************* * * MPUSBAPI Library Version 1.00 * ********************************************************************* * FileName: _mpusbapi.cpp * Dependencies: See #include section below. * Compiler: Borland C++ Builder 6 * Company: Copyright (C) 2004 by Microchip Technology, Inc. * * Software License Agreement * * The software supplied herewith by Microchip Technology Incorporated * (the “Company”) for its PICmicro® Microcontroller is intended and * supplied to you, the Company’s customer, for use solely and * exclusively on Microchip PICmicro Microcontroller products. The * software is owned by the Company and/or its supplier, and is * protected under applicable copyright laws. All rights are reserved. * Any use in violation of the foregoing restrictions may subject the * user to criminal sanctions under applicable laws, as well as to * civil liability for the breach of the terms and conditions of this * license. * * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. * * Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Ross Fosler 9/2/04 Implemented MPUSBGetDeviceLink() * Rawin Rojvanit 11/19/04 Original version 1.00 completed ********************************************************************/ /////////////////////////////////////////////////////////////////////////////// // MPUSBGetDLLVersion : get mpusbapi.dll revision level // // Input: // None // Output: // 32-bit revision level MMMMmmmm // /////////////////////////////////////////////////////////////////////////////// // MPUSBIsVidPidEqual : Compares the pVID_PID string against the DeviceInstance // string retrieved from the registry using the DevicePath subkey. // This function should be called only from MPUSBGetDevicePath(). // // Note: // All Windows version has the DeviceClasses information stored in: // HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Control\\DeviceClasses\\ // {GUID_DEVINTERFACE_MCHPUSB}\\ // Win98SE,ME have different DevicePath string format from 2K,XP. // It does not contain vid&pid information in the DevicePath. // Thus necessitating the needs to check the DeviceInstance string in the // registry. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBGetDeviceLink : Returns the path to device hardware with a given // instance number. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBGetDeviceCount : Returns the number of devices with matching VID & PID // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBOpen : Returns the handle to the endpoint pipe with matching VID & PID // // All pipes are opened with the FILE_FLAG_OVERLAPPED attribute. // This allows MPUSBRead,MPUSBWrite, and MPUSBReadInt to have a time-out value. // // Note: Time-out value has no meaning for Isochronous pipes. // // instance - An instance number of the device to open. // Typical usage is to call MPUSBGetDeviceCount first to find out // how many instances there are. // It is important to understand that the driver is shared among // different devices. The number of devices returned by // MPUSBGetDeviceCount could be equal to or less than the number // of all the devices that are currently connected & using the // generic driver. // // Example: // if there are 3 device with the following PID&VID connected: // Device Instance 0, VID 0x04d8, PID 0x0001 // Device Instance 1, VID 0x04d8, PID 0x0002 // Device Instance 2, VID 0x04d8, PID 0x0001 // // If the device of interest has VID = 0x04d8 and PID = 0x0002 // Then MPUSBGetDeviceCount will only return '1'. // The calling function should have a mechanism that attempts // to call MPUSBOpen up to the absolute maximum of MAX_NUM_MPUSB_DEV // (MAX_NUM_MPUSB_DEV is defined in _mpusbapi.h). // It should also keep track of the number of successful calls // to MPUSBOpen(). Once the number of successes equals the // number returned by MPUSBGetDeviceCount, the attempts should // be aborted because there will no more devices with // a matching vid&pid left. // // pVID_PID - A string containing the PID&VID value of the target device. // The format is "vid_xxxx&pid_yyyy". Where xxxx is the VID value // in hex and yyyy is the PID value in hex. // Example: If a device has the VID value of 0x04d8 and PID value // of 0x000b, then the input string should be: // "vid_04d8&pid_000b" // // pEP - A string of the endpoint number on the target endpoint to open. // The format is "\\MCHP_EPz". Where z is the endpoint number in // decimal. // Example: "\\MCHP_EP1" // // This arguement can be NULL. A NULL value should be used to // create a handles for non-specific endpoint functions. // MPUSBRead, MPUSBWrite, MPUSBReadInt are endpoint specific // functions. // All others are not. // Non-specific endpoint functions will become available in the // next release of the DLL. // // Note: To use MPUSBReadInt(), the format of pEP has to be // "\\MCHP_EPz_ASYNC". This option is only available for // an IN interrupt endpoint. A data pipe opened with the // "_ASYNC" keyword would buffer the data at the interval // specified in the endpoint descriptor upto the maximum of // 100 data sets. Any data received after the driver buffer // is full will be ignored. // The user application should call MPUSBReadInt() often // enough so that the maximum limit of 100 is never reached. // // dwDir - Specifies the direction of the endpoint. // Use MP_READ for MPUSBRead, MPSUBReadInt // Use MP_WRITE for MPUSBWrite // // dwReserved Future Use // // Summary of transfer type usage: // ============================================================================ // Transfer Type Functions Time-Out Applicable? // ============================================================================ // Interrupt - IN MPUSBRead, MPUSBReadInt Yes // Interrupt - OUT MPUSBWrite Yes // Bulk - IN MPUSBRead Yes // Bulk - OUT MPUSBWrite Yes // Isochronous - IN MPUSBRead No // Isochronous - OUT MPUSBWrite No // ============================================================================ // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBGetDeviceDescriptor : Returns the Device Descriptor Data // // **** INCOMPLETE **** // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBRead : // // handle - Identifies the endpoint pipe to be read. The pipe handle must // have been created with MP_READ access attribute. // // pData - Points to the buffer that receives the data read from the pipe. // // dwLen - Specifies the number of bytes to be read from the pipe. // // pLength - Points to the number of bytes read. MPUSBRead sets this value to // zero before doing any work or error checking. // // dwMilliseconds // - Specifies the time-out interval, in milliseconds. The function // returns if the interval elapses, even if the operation is // incomplete. If dwMilliseconds is zero, the function tests the // data pipe and returns immediately. If dwMilliseconds is INFINITE, // the function's time-out interval never elapses. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBWrite : // // handle - Identifies the endpoint pipe to be written to. The pipe handle // must have been created with MP_WRITE access attribute. // // pData - Points to the buffer containing the data to be written to the pipe. // // dwLen - Specifies the number of bytes to write to the pipe. // // pLength - Points to the number of bytes written by this function call. // MPUSBWrite sets this value to zero before doing any work or // error checking. // // dwMilliseconds // - Specifies the time-out interval, in milliseconds. The function // returns if the interval elapses, even if the operation is // incomplete. If dwMilliseconds is zero, the function tests the // data pipe and returns immediately. If dwMilliseconds is INFINITE, // the function's time-out interval never elapses. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBReadInt : // // handle - Identifies the endpoint pipe to be read. The pipe handle must // have been created with MP_READ access attribute. // // pData - Points to the buffer that receives the data read from the pipe. // // dwLen - Specifies the number of bytes to be read from the pipe. // // pLength - Points to the number of bytes read. MPUSBRead sets this value to // zero before doing any work or error checking. // // dwMilliseconds // - Specifies the time-out interval, in milliseconds. The function // returns if the interval elapses, even if the operation is // incomplete. If dwMilliseconds is zero, the function tests the // data pipe and returns immediately. If dwMilliseconds is INFINITE, // the function's time-out interval never elapses. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. // /////////////////////////////////////////////////////////////////////////////// // MPUSBClose : closes a given handle. // // Note that "input" and "output" refer to the parameter designations in calls // to this function, which are the opposite of common sense from the // perspective of an application making the calls. //