usbclasses/pictbridgeengine/inc/pictbridge.h
changeset 0 1e05558e2206
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/usbclasses/pictbridgeengine/inc/pictbridge.h	Thu Dec 17 09:14:30 2009 +0200
@@ -0,0 +1,274 @@
+/*
+* Copyright (c) 2006, 2007 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:  This class defines and implements the API for UI engine. 
+*
+*/
+
+
+#ifndef PICTBRIDGE_H
+#define PICTBRIDGE_H
+
+#include "dpsdefs.h"
+#include <rptp.h>
+
+class TDpsXmlString;
+class CDpsUsbNotifier;
+class TMDpsOperation;
+class TDpsEvents;
+class CDpsStateMachine;
+class TDpsConfigPrintReq;
+
+NONSHARABLE_CLASS(CDpsEngine) : public CBase
+    {
+    public:
+        enum TConnectionStatus
+            {
+            ENotConnected = 1,
+            // ptp printer is connected
+            EPrinterConnected,
+            // ptp printer is disconnected
+            EPrinterDisconnected,
+            // in ptp personality, but device other than printer connected
+            EOtherConnected,
+            // in personality other than ptp and device is connected 
+            EWrongPrintModeConnected
+            };
+	        
+    public:
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   The client should always call this function to get the Dps 
+        *   engine object.
+        *   This function guarantees there is only one engine in the 
+        *   thread, a singleton.  	
+        *   @return CDpsEngine* the only Dps Engine instance in a thread
+        *   
+        */
+        IMPORT_C static CDpsEngine* GetEngineL();
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *	Deletes the dps engine object. 
+        */
+        IMPORT_C void Delete();
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *	Sets the personality to PTP. This must be the first call after 
+        *   the client has got the CDpsEngine object and should only be
+        *   called once.
+        *   @param aStatus the asynchronous request and it has the connect
+        *   state after returned. The client can use this value to get the
+        *   current connect status.        
+        */
+        IMPORT_C void SetPrintMode(TRequestStatus& aStatus);
+        							 
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Cancels the SetPrintMode request        
+        */        							 
+        IMPORT_C void CancelPrintMode();
+						     
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Registers connection notification. This function can inform 
+        *   the connection and the disconnect, two states. Connection: the
+        *   personality has been set to PTP by SetPrintMode, but the cable
+        *   is not connected at the moment. The connection will be informed
+        *   by this function. 
+        *   Disconnect: the user has unplugged the cable or changed 
+        *   personality.    
+        *   
+        *   @param aStatus the asynchronous request status and it has the 
+        *   connect state after returned.
+        */     
+        IMPORT_C void ConnectStateNotify(TRequestStatus& aStatus);
+				     					
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Registers Dps event notification. There are two events: jobStatus
+        *   and deviceStatus. This function is called immediately after 
+        *   ConnecSatetNotify call. After this call, the client should issue 
+        *   ConfigPrintService request to configure the printer.
+        *   @param aParam this parameter serves as out parameter. After
+        *   processing the event from the printer, Dps engine will put
+        *   the correct value to this parameter. As the result, the client
+        *   can get the event by accessing this parameter after this request
+        *   gets answered. So the client should have it as a class variable
+        *   @param aStatus the asynchronous status. 
+        */
+        IMPORT_C void DpsEventNotify(TDpsEvents& aParam, 
+                                     TRequestStatus& aStatus);
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Cancels Dps event notification. The client only needs to call
+        *   this to reset the state of the dps engine and it must be called
+        *   after CancelDpsRequest().
+        */
+        IMPORT_C void CancelDpsEventNotify();
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Starts a Dps operation.
+        *   If this function returned with error, e.g. leaving, the client
+        *   should call CancelDpsRequest(), to cancel the pending request.
+        *   @param aRequest the Dps operation. It includes both request and 
+        *   reply. The client should fill in the request parameter and the 
+        *   Dps engine will fill in the reply paramter when this operation
+        *   is finished. The client should declare it as a class variable.
+        *   @param aStatus the asynchronous status
+        */
+        IMPORT_C void DoDpsRequestL(TMDpsOperation* aRequest, 
+                                    TRequestStatus& aStatus);
+		
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Cancels the dps operation. Calling this will reset the state of 
+        *   the dps engine, either because of error happened or the client
+        *   wants to do this on purpose. In most cases, the client never need
+        *   to cancel the ongoing request because the request will end very 
+        *   quick, normally within several million seconds. The client normally
+        *   waits until the request is finished, either succesfully or
+        *   failed indicated by timeout.
+        */        
+        IMPORT_C void CancelDpsRequest();
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Reads the phone dps configuration from the resource file
+        *   @param aConfig the dps configuration is returned by this parameter
+        */
+        IMPORT_C void GetDpsConfigL(TDpsConfigPrintReq& aConfig);
+        
+        /**
+        *   @since 3.2
+        *   @lib pictbridge.lib
+        *
+        *   Gets the folder where the printer configure file should be kept. 
+        *   The print App needs a file to store the printer configure when it
+        *   first calls configPrintService Dps request. The print app can 
+        *   quit at anytime while the ptpserver (stack) is still running. 
+        *   Since the ptpstack is keeping the session with the printer, the 
+        *   printer always does not excute the second onward 
+        *   configPrintService request. As the result, the restarted print app
+        *   cannot get the printer configure. So there must be a file for 
+        *   keeping this information and it will be deleted by ptpserver when
+        *   it quits, e.g. when the connection with the printer is lost.
+        *   @return TDesC& the folder descriptor
+        */
+        IMPORT_C const TDesC& DpsFolder() const;
+            
+        /**
+        *   Gets the Dps event object
+        *   @return TDpsEvents* the pointer to the Dps event.
+        */
+        TDpsEvents* Event() const;
+            
+        /**
+        *  Gets the ptp server reference
+        *  @return RPtp& the reference to ptp server.
+        */
+        RPtp& Ptp();
+            
+        /**
+        *  Gets the dps constant strings
+        *  @return TDpsGlobalData* the pointer to dps constant strings.
+        */
+        TDpsXmlString* DpsParameters() const;
+         
+        /**
+        * @return dps event notify AO status
+        *   
+        */
+        TRequestStatus*& EventRequest();
+            
+        /**
+        * @return dps request AO status
+        */
+        TRequestStatus*& OperationRequest();
+         
+        /**
+        * @return connection notify AO status
+        */               
+        TRequestStatus*& PrinterConnectRequest();
+        
+        /**
+        *  Sets the Dps file folder. 
+        *  @param aFolder the foler location, readed from Ptp server/stack 
+        */
+        void SetDpsFolder(const TDesC& aFolder);
+        
+            
+    private:
+        
+        /**
+        *   Prohibits the destructor called by the client. To delete engine object
+        *   Delete() must be called
+        */
+        ~CDpsEngine();  
+        
+        /**
+        *   Second phase constructor. Operations which might leave should 
+        *   be called here
+        */
+        void ConstructL();
+              
+    private:
+        // string constant, owned by this class
+        TDpsXmlString* iDpsParameters;
+        // dps engine state machine, owned by this class
+        CDpsStateMachine *iDpsOperator;
+        // dps operation AO request, owned by this class
+        TRequestStatus* iDpsOperationRequest;
+        // dps event AO request, owned by this class
+        TRequestStatus* iDpsEventRequest;
+        // printer connection/disconnection AO request, owned by this class
+        TRequestStatus* iPrinterConnectRequest;
+        
+        // usb cable connection/disconnection notifier, owned by this class
+        CDpsUsbNotifier *iUsbNotifier;
+                
+        // out parameter for events (NotifyJobStatus and
+        // NotifyDeviceStauts), it is
+        // passed from UI engine, not owned by this class  
+        TDpsEvents* iOutEvent;
+        
+        // Ptp Server session, owned by this class
+        RPtp    iPtp;
+        // the folder where all dps releated files should be stored              
+        TFileName iDpsFolder;  
+    };
+
+#endif