ncfwapi.h

CE下 NET2778 NDIS Drivers, 在每个平台上都可以使用

    //  - The client can use this number in a single transfer completion routine to
    //    know which endpoint completed. It can use the number to index into a client
    //    array
    NCBYTE LogicalEp;

    ///////////////////////////////////////////////////////////////////////////
    // USB endpoint descriptor for this endpoint
    //  - Refers to an endpoint descriptor in the client configuration
    //  - Set by the API in its Set Configuration handler
    //  - Not applicable to Endpoint Zero
    PUSB_ENDPOINT_DESCRIPTOR EpDescriptor;

    ///////////////////////////////////////////////////////////////////////////
    // Default transfer object:
    //  - Once initialized, the endpoint's Transfer refers to this default Transfer Object.
    //  - Simple implementations may choose to use the endpoint's default transfer 
    //    object for all the endpoint's transfers. More complex client implementations, 
    //    applying perhaps scatter-gather techniques, will ignore the default transfer 
    //    object, and instead manage several of its own transfer objects.
    NC_TRANSFER_OBJECT DefaultTransferObject;

    ///////////////////////////////////////////////////////////////////////////
    // Endpoint direction:
    //  - For speed and convenience, the endpoint direction (found in the endpoint 
    //    descriptor) is duplicated here. If TRUE, the endpoint direction is IN
    //  - Must be FALSE for Endpoint Zero: To determine the direction of a Control
    //    Transfer on endpoint zero, test the Data Transfer Direction bit (bit 7) 
    //    in bmRequestType of the Setup Request (See USB 2.0: 9.3)
    BOOL DirectionIn;

    ///////////////////////////////////////////////////////////////////////////
    // Endpoint stall status:
    //  - If set, the endpoint will return stall status to the host
    //  - To change the endpoint's stall condition, set or clear this boolean and call 
    //    the API's Endpoint Stall routine
    BOOL Stall;

    ///////////////////////////////////////////////////////////////////////////
    // Endpoint event code
    //  - Endpoint event codes are associated with the Endpoint Event Handler. 
    //  - When an endpoint event occurs, the API sets an event-appropriate code 
    //    and calls the endpoint event handler.
    //  - The client application should return More Processing Required for any
    //    device events it does not specifically handle.
    //  - Tip: The API initialization routine installs a default handler. The default
    //    handler takes no action. If the client requires endpoint event notification, it 
    //    should replace the default handler with its own.
    //  - Tip: Be sure to differentiate Endpoint event codes from other API event codes!
    NC_ENDPOINT_EVENT_CODE EventCode;

    ///////////////////////////////////////////////////////////////////////////
    // Endpoint event handler
    //  - The endpoint event handler is associated with endpoint event codes.
    //  - See Endpoint Event Codes
    NCSTATUS(*EndpointEventHandler)(struct _NC_ENDPOINT_OBJECT * Endpoint);

    ///////////////////////////////////////////////////////////////////////////
    // Client may place any private context here (at any time!)
    //  - Client contexts are ignored by the API
    //  - More context entries can be added as needed
    void * ClientContext1;

    ///////////////////////////////////////////////////////////////////////////
    // Chip-specific extension to Endpoint Object
    //  - Client applications may find chip-specific extensions to NetChip's standard
    //    endpoint structure here. 
    //  - Tip: The extension is not defined for all chips!
    NC_ENDPOINT_OBJECT_EXTENSION Ex;

    ///////////////////////////////////////////////////////////////////////////
    // Private Endpoint Object members
    //  - Private members are used by NcApi to support endpoint transfers
    //  - Client applications should not require access to members of this structure
    NC_PRIVATE_ENDPOINT_OBJECT Priv;

} NC_ENDPOINT_OBJECT, * PNC_ENDPOINT_OBJECT;


//////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
// USB bus speeds:
//  - Code indicates USB connection speed (High, Full)
typedef enum _NC_BUS_SPEED
{
    NC_BUS_SPEED_UNKNOWN = 0,               // Bus speed has not yet been determined
    NC_BUS_SPEED_HIGH,                      // High Speed (HS, 2.0, 480MBit/S)
    NC_BUS_SPEED_FULL,                      // Full Speed (FS, 1.1, 12MBit/S)
    END_OF_NC_BUS_SPEED                     // Placeholder: End of bus speed list (not a valid bus speed!)
} NC_BUS_SPEED;

//////////////////////////////////////////////////////////////////////////////
// NetChip chip states
typedef enum _NC_CHIP_STATE
{
    //////////////////////////////////////////////////////////////////////////
    // Invalid chip state:
    //  - Chip state has not yet been determined
    //  - After "Are You There" chip test, state should change to Running
    NC_CHIP_STATE_INVALID = 0,              // Chip state has not yet been determined

    //////////////////////////////////////////////////////////////////////////
    // Chip is suspended:
    //  - Chip is in it's low-power suspend mode
    //  - Chip clock is not running
    //  - Accessing a register may wake suspended chip (See I/O Wakeup Enable)
    //  - Tip: USB suspend and chip suspend are related but different!
    //  - See API Suspend Chip function
    NC_CHIP_STATE_SUSPENDED,

    //////////////////////////////////////////////////////////////////////////
    // Chip is running:
    NC_CHIP_STATE_RUNNING

} NC_CHIP_STATE, * PNC_CHIP_STATE;

//////////////////////////////////////////////////////////////////////////////
// USB power states
typedef enum _NC_USB_POWER
{
    //////////////////////////////////////////////////////////////////////////
    // Invalid power state
    //  - Should cause an assert!
    NC_USB_POWER_INVALID = 0,

    //////////////////////////////////////////////////////////////////////////
    // Power OFF
    //  - USB cable disconnected (VBUS is FALSE)
    //  - No power can be drawn from the upstream connection
    NC_USB_POWER_OFF,

    //////////////////////////////////////////////////////////////////////////
    // Power ON
    //  - USB cable connected (VBUS is TRUE)
    //  - In this state, configured or unconfigured power is available from
    //    the upstream connection
    NC_USB_POWER_ON,

    //////////////////////////////////////////////////////////////////////////
    // Connected to suspended host
    //  - USB cable connected (VBUS is TRUE)
    //  - Only suspend current can be drawn from the upstream connection
    //  - Note that Power Suspend State is independent from the chip's suspend state
    NC_USB_POWER_SUSPEND

} NC_USB_POWER, * PNC_USB_POWER;

//////////////////////////////////////////////////////////////////////////////
// Device event codes:
//  - Codes indicating various device event have occurred:
//  - The client application should return More Processing Required for any
//    device events it does not specifically handle.
typedef enum _NC_DEVICE_EVENT_CODE
{
    // Error! Unknown event
    //  - All known, real event codes are non-zero
    NC_DEVICE_EVENT_UNKNOWN = 0,

    //////////////////////////////////////////////////////////////////////////
    // VBUS True:
    //  - Cable has been connected to a powered host or hub
    NC_DEVICE_EVENT_VBUS_TRUE,

    //////////////////////////////////////////////////////////////////////////
    // VBUS False:
    //  - Cable has been unplugged (or host or hub has been unplugged or depowered)
    //  - Depending on your device power policy, you may want to reduce system 
    //    power consumption on this event
    NC_DEVICE_EVENT_VBUS_FALSE,

    //////////////////////////////////////////////////////////////////////////
    // Root port reset:
    //  - End of USB reset signalling detected
    //  - The host is expected to start an enumeration sequence (e.g. Set Address, 
    //    Get Descriptor (DEVCE), etc.) soon after the end of USB reset signalling
    NC_DEVICE_EVENT_ROOT_PORT_RESET,

    //////////////////////////////////////////////////////////////////////////
    // Device Request event:
    //  - An eight-byte setup request packet received from host
    //  - Clients get the "first-chance" to handle ALL setup requests (Standard, 
    //    Vendor, Class and even invalid requests). The client's return code
    //    indicates whether the API should apply its standard handlers to the 
    //    request. It is important for the client to return the correct status code.
    //  - Client return codes (Important!):
    //     - Success: Client completely handled the request. The API will not 
    //       apply any further processing. Typically, clients apply this code when
    //       the client completely handles its Class and/or Vendor specific requests.
    //     - Unsuccessful OR More Processing Required: The API will apply its standard 
    //       handlers to the request. Event handlers that do not specifically implement
    //       a Device Request handler should return More Processing Required. If the
    //       API is not able to handle the request (e.g. a non-standard request) the API
    //       will stall endpoint zero.
    //     - Tip: A client may stall a request by calling the API Endpoint Stall
    //       routine. In this case, the client MUST return Success to prevent
    //       the API from processing the request further!
    //  - Generally, a client's Device Request handler returns More Processing Required 
    //    for all requests except for the Class or Vendor requests it supports.
    //  - Advanced devices, such as devices supporting more than one configuration, 
    //    more than one interface, or devices with dynamic power-source capabilities 
    //    may need to parse and completely handle certain Standard Requests.
    //  - See USB 2.0: 9.3
    // Data and status phase:
    //  - Client may optionally start a data phase transfer from within its Device Request
    //    Event handler. To start the data phase transfer, the client calls API's 
    //    standard Endpoint Transfer routine.
    //    The API ensures proper handling of data phase packets. As with normal 
    //    transfers the client may install a completion handler for Endpoint Zero transfers.
    //  - API handles the status phase automatically. At the beginning of the status phase,
    //    if the client started a data phase, the client's Endpoint Zero completion handler 
    //    is called.
    NC_DEVICE_EVENT_DEVICE_REQUEST,

    //////////////////////////////////////////////////////////////////////////
    // Set Configuration event:
    //  - Host has issued a Set Configuration request. Before calling the client,
    //    the API sets USB Configuration Number in the Device Object to the host's
    //    requested configuration number. The client's set configuration handler
    //    should parse the configuration number.
    //  - A non-zero configuration number indicates the host has received and 
    //    accepted the device's configuration and is now entering the configured 
    //    state. In the configured state, the device and host can transfer packets 
    //    over data endpoints. While handling a non-zero Set Configuration event, 
    //    the client may create data endpoints and request data transfers to the API.
    //  - Tip: A non-zero Set Configuration request is the final step of successful
    //    enumeration. It indicates the host's device-specific client driver has
    //    successfully loaded, started, and accepted the device's configuration.
    //  - Tip: USB devices must minimally support configurations zero (de-configured) 
    //    and one (configured). Hosts rarely (except for compliance testing) issue
    //    a Set Configuration for configuration zero.
    //  - Client return codes: The client's Set Configuration event handler may 
    //    return one of these codes:
    //     - Success: The requested configuration is acceptable to the client. The 
    //       API continues configuration.
    //     - More Processing Required: Client event handlers that do not specifically
    //       implement a Set Configuration event handler should return this code. The