/*
* 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 <e32base.h>

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<TUint>& 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