diff -r 000000000000 -r c9bc50fca66e usbmgmt/usbmgr/host/fdf/production/fdcbase/public/fdcinterface.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/usbmgmt/usbmgr/host/fdf/production/fdcbase/public/fdcinterface.h Tue Feb 02 02:02:59 2010 +0200 @@ -0,0 +1,158 @@ +/* +* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + +/** + @file + @publishedPartner + @released +*/ + +#ifndef FDCINTERFACE_H +#define FDCINTERFACE_H + +#include + +class TUsbDeviceDescriptor; +class TUsbConfigurationDescriptor; + +/** +The UID of this FDC interface. +If the FDC API ever has to change, a new UID and associated M class will be +created. New FDC implementations may implement the new API. Old (non-updated) +FDCs will still work because the FDF examines at run-time which interfaces are +supported by any particular FDC. +*/ +const TInt KFdcInterfaceV1 = 0x10282B4C; + +/** +Mixin for the FDC API. +*/ +class MFdcInterfaceV1 + { +public: + /** + Called when a device is attached. + + The Function Driver Framework has determined that this Function Driver is + the most suitable to drive at least one of the interfaces in the device's + selected configuration. + + Each call to this method represents an attempt by the Function Driver + Framework to get the Function Driver Controller to take ownership of + interfaces (exactly one Function) on the device. + + Not all the interfaces contained may be relevant to this Function Driver. + Some interfaces may be relevant to this Function Driver, but should *not* + be claimed in this call, as described below. + + The device's entire device descriptor and configuration descriptor are + given. + + The Function Driver Framework provides a collection (aInterfaces) of + interfaces which it is offering to the Function Driver Controller. The + Function Driver Controller MUST take ownership of the first of these by + calling MFdcPluginObserver::TokenForInterface (the Function Driver + Controller was selected by the Function Driver Framework on the basis of + its default_data field matching this particular interface). The Function + Driver Controller MUST also take ownership of as many following interfaces + as make up a single Function as defined by the relevant USB Class, again + by calling MFdcPluginObserver::TokenForInterface for them. + + The Function Driver Controller may examine interface descriptors for the + interfaces it is being offered using the bInterfaceNumber items in + aInterfaces, and the TUsbConfigurationDescriptor given + (aConfigurationDescriptor). + + Once exactly one Function has been claimed, the Function Driver Controller + may return from this method. + The Function Driver Framework does not make further attempts to load + Function Drivers for the interfaces that have been claimed, whether an + error is returned or not. + If an error is returned, then (a) the FDF will send a driver loading error + to USBMAN, and (b) the FDC must not have opened ANY RUsbInterfaces as a + result of this call to Mfi1NewFunction. + It is important for the Function Driver Controller to claim all the + interfaces it should, even if it finds out early on that it won't be able + to handle the Function for environmental or other reasons. + The FDC may also return an error indicating that the Class-specific + descriptors are incorrectly formatted. + + The FD is not required to open RUsbInterface handles during + Mfi1NewFunction. If it does, then it can pass any failure back as a return + value to Mfi1NewFunction and this will be relayed to USBMAN as a driver + loading error. If it does not, then the FD must itself take responsibility + for relaying relevant failures to the user. (This is in aid of the 'no + silent failures' requirement.) + + This method may be called zero or more times for each device attached, + depending on the interfaces present in the device's active configuration + and on the other FDs present on the phone. If this function is called (and + returns KErrNone) one or more times on a particular FDC, then + Mfi1DeviceDetached will be called exactly once when the device is detached. + If on device attachment this function is called one or more times for a + particular FDC, and each time the FDC returns an error, then no device + detachment notification will be given to that FDC. Hence any RUsbInterface + handles successfully opened in a call to this function should be cleaned + up immediately if the function returns error. + + @see MFdcPluginObserver::TokenForInterface. + + @param aDeviceId This is the ID of the new device. This identifier is + private between the Function Driver Framework and the Function Driver. Its + significance is to identify a device when it is removed (see + Mfi1DeviceDetached). It is not equivalent to the device address or to + anything else. + + @param aInterfaces A collection of interface numbers (bInterfaceNumber) + which are being offered to the Function Driver Controller. The Function + Driver Controller uses items in this array in calls to + MFdcPluginObserver::TokenForInterface. Ownership of the array is retained + by the FDF. + + @param aDeviceDescriptor The device descriptor of the device. Ownership is + retained by the FDF. + + @param aConfigurationDescriptor The selected configuration descriptor of + the device. Ownership is retained by the FDF. + + @return Error. On return (ANY error code), the interfaces claimed in calls + to MFdcPluginObserver::TokenForInterface are claimed by this FDC. If an + error is returned, the FDC must cause no interface handles to be opened as + a result of this call. The FDF will indicate a failure to load drivers to + USBMAN. + */ + virtual TInt Mfi1NewFunction(TUint aDeviceId, + const TArray& aInterfaces, + const TUsbDeviceDescriptor& aDeviceDescriptor, + const TUsbConfigurationDescriptor& aConfigurationDescriptor) = 0; + + /** + Called when a device is detached. + The device is one of those which have previously been notified to the + Function Driver in a Mfi1NewFunction call. + Any RUsbInterface handles which were opened as a result of the + corresponding earlier Mfi1NewFunction call should be closed as they + will be useless. + + @param aDeviceId This serves to identify the device which has disappeared. + This will be the device ID given in a previously completed + Mfi1NewFunction call. + */ + virtual void Mfi1DeviceDetached(TUint aDeviceId) = 0; + }; + +#endif // FDCINTERFACE_H