1 /* |
|
2 * Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Contains the following interfaces: MProtPrintingDevice, |
|
15 * MProtIdleObserver, MProtPrintEventObserver and MProtDiscoveryObserver. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 #ifndef MPROTPRINTINGDEVICE_H |
|
21 #define MPROTPRINTINGDEVICE_H |
|
22 |
|
23 #include <e32base.h> |
|
24 |
|
25 #include "tprinter.h" |
|
26 #include "tprintcapability.h" |
|
27 #include "tidleevent.h" |
|
28 |
|
29 const TInt DEVICE_ID_FIELD_MASK = 0x03FFFFFF; // most significant bits: 0000 0011 rest is 1's |
|
30 const TInt PROTOCOL_ID_FIELD_MASK = 0xFC000000; // most significant bits: 1111 1100 |
|
31 const TInt PROTOCOL_ID_CLEAR_MASK = 0x0000003F; // less siginificant bits: 0011 1111 |
|
32 const TInt PROTOCOL_ID_BIT_COUNT = 6; |
|
33 |
|
34 |
|
35 /** |
|
36 * @brief Interface to be implemented by a class observing the discovery events of a class implementing MProtPrintingDevice. |
|
37 * |
|
38 * Interface used by a Protocol implementing "MProtPrintingDevice" to report back any device found or not found and |
|
39 * the general status of the discovery process. This should be implemented by the class using "MProtPrintingDevice"; in |
|
40 * this case, it's already implemented in a class in the Image Print Library. |
|
41 */ |
|
42 class MProtDiscoveryObserver |
|
43 { |
|
44 public: |
|
45 virtual void FoundDeviceL( TPrinter& aDeviceInfo ) = 0; |
|
46 virtual void RemoveDeviceL( TPrinter& aDeviceInfo ) = 0; |
|
47 |
|
48 /** |
|
49 * @brief |
|
50 * @param aStatus ( EDiscovering | ECancellingDiscovery | EDoneDiscovery | EDiscoveryFinished ) |
|
51 * EDiscovering = currently discovering |
|
52 * ECancellingDiscovery = cancel request on discovery |
|
53 * EDiscoveryFinished = on discovery time-out |
|
54 * @param aErrorCode |
|
55 * @param aErrorStringCode |
|
56 */ |
|
57 virtual void DiscoveryStatusL( TInt aStatus, |
|
58 TInt aErrorCode, |
|
59 TInt aErrorStringCode = KErrNone ) = 0; |
|
60 }; |
|
61 |
|
62 /** |
|
63 * @brief Interface to be implemented by a class observing the printing events of a class implementing MProtPrintingDevice. |
|
64 * |
|
65 * Interface used by a Protocol implementing "MProtPrintingDevice" to report back the printing progress, any error or |
|
66 * the printer status. This should be implemented by the class using "MProtPrintingDevice"; in this case, it's already |
|
67 * implemented in a class in the Image Print Library. |
|
68 * These methods should be used only when actual printing is ongoing |
|
69 */ |
|
70 class MProtPrintEventObserver |
|
71 { |
|
72 public: |
|
73 /** |
|
74 * @brief Method to inform observer about printing proggress. |
|
75 * |
|
76 * @param aStatus Defines the printing status defined in ImagePrint.h. |
|
77 * @param aPercent Percents of job readiness. |
|
78 * @param aJobStateCode Job's state defined in PrintMessageCodes.h. |
|
79 */ |
|
80 virtual void PrintJobProgressEvent( TInt aStatus, |
|
81 TInt aPercent, |
|
82 TInt aJobStateCode ) = 0; |
|
83 |
|
84 /** |
|
85 * @brief Method to inform observer about error occured during printing. |
|
86 * |
|
87 * @param aErrorCode Defines the error code that is symbian wide or defined in PrintMessageCodes.h. |
|
88 * @param aErrorStringCode Reserved for future use. |
|
89 */ |
|
90 virtual void PrintJobErrorEvent( TInt aErrorCode, |
|
91 TInt aErrorStringCode = KErrNone ) = 0; |
|
92 |
|
93 /** |
|
94 * @brief Method to inform observer about error concerning the printing device. |
|
95 * |
|
96 * @param aErrorCode Defines the error code that is symbian wide or defined in PrintMessageCodes.h. |
|
97 * @param aErrorStringCode Reserved for future use. |
|
98 */ |
|
99 virtual void PrinterStatusEvent( TInt aErrorCode, |
|
100 TInt aErrorStringCode = KErrNone ) = 0; |
|
101 |
|
102 // DEPRECATED - DO NOT USE |
|
103 virtual void PreviewImageEvent( TInt aFsBitmapHandle ) = 0; |
|
104 |
|
105 // DEPRECATED - DO NOT USE |
|
106 virtual void ShowMessageL( TInt aMsgLine1Code, |
|
107 TInt aMsgLine2Code ) = 0; |
|
108 |
|
109 // DEPRECATED - DO NOT USE |
|
110 virtual TBool AskYesNoQuestionL( TInt aMsgLine1Code, |
|
111 TInt aMsgLine2Code ) = 0; |
|
112 |
|
113 // DEPRECATED - DO NOT USE |
|
114 virtual const TDesC& AskForInputL( TInt aMsgLine1Code, |
|
115 TInt aMsgLine2Code ) = 0; |
|
116 }; |
|
117 |
|
118 /** |
|
119 * @brief Interface to be implemented by CImagePrint. It is used to report |
|
120 * anything related to status changes in the handling protocol. |
|
121 * @sa MProtPrintingDevice::RegisterIdleObserver |
|
122 */ |
|
123 class MProtIdleObserver |
|
124 { |
|
125 public: |
|
126 /** Called by a protocol to notify CImagePrint of events. The meaning of the event and associated error and mesage codes |
|
127 * is protocol dependant. This should be used only when actual printing is not ongoing. |
|
128 */ |
|
129 virtual void StatusEvent( const TEvent &aEvent, |
|
130 TInt aError, |
|
131 TInt aMsgCode ) = 0; |
|
132 }; |
|
133 |
|
134 /** |
|
135 * @brief Interface to be implemented in the Polymorphic DLLs. |
|
136 * |
|
137 * Interface to be implemented by any printing protocol that wants to be added to the Image Print library, so it can |
|
138 * be seen by the library and used in a transparent way. This implementation should be encapsulated within a Polymorphic |
|
139 * DLL and put in a specific directory. |
|
140 */ |
|
141 class MProtPrintingDevice |
|
142 { |
|
143 public: |
|
144 // General. |
|
145 /** |
|
146 * @brief Part of the standard construction pattern. |
|
147 * @param aDLLPath Path where the DLL was found so it can know where it is located and use that information |
|
148 * when looking for resource files and such. The path includes the DLL itself. |
|
149 */ |
|
150 virtual void ConstructL( const TDesC& aDLLPath ) = 0; |
|
151 /** |
|
152 * @brief Reports the Version of the DLL. |
|
153 * @return A TVersion object containing the version of the protocol. |
|
154 */ |
|
155 virtual TVersion Version() = 0; |
|
156 /** |
|
157 * @brief Returns the Protocols supported by the DLL. It can be any of the KImagePrint_PrinterProtocol* constants. |
|
158 * @return An OR'ed value with the supported protocols information. |
|
159 */ |
|
160 virtual TUint SupportedProtocols() = 0; |
|
161 // Discovery. |
|
162 /** |
|
163 * @brief Starts the discovery process. |
|
164 * |
|
165 * This process is to find whatever printing device is available nearby. After this call server waits |
|
166 * DiscoveryStatusL from MProtDiscoveryObserver to be called with value aStatus = EDiscoveryFinished |
|
167 * after the discovey is finished. |
|
168 * @param aObserver The discovery observer. |
|
169 * @param aProtocol Used to indicate what protocols to search for. 0 = all, 1 = BPP, 2 = BIP, 4 = OPP, 8 = DPOF, 16 = PB. |
|
170 * @return Any standard Symbian error code. |
|
171 */ |
|
172 virtual void StartDiscoveryL( MProtDiscoveryObserver& aObserver, |
|
173 TUint aProtocol = 0 ) = 0; |
|
174 /** |
|
175 * @brief Removes a specified cached printer. |
|
176 * @param[in] aDeviceID The ID of the printer the client wants to remove. |
|
177 * @return Any standard Symbian error code or ( KErrInvalidSequence and KErrInvalidData ). |
|
178 */ |
|
179 virtual TInt RemoveCachedDeviceL( TInt aDeviceID ) = 0; |
|
180 |
|
181 /** |
|
182 * @brief Cancels the discovery process. |
|
183 * The caller expects to get notification of cancelled discovery via 'DiscoveryStatusL' with value 'EDiscoveryCancelling' |
|
184 * @param[in] aDoCallBack Flag to indicate whether to call back the observer or not. Default = True. |
|
185 */ |
|
186 virtual void CancelDiscovery( TBool aDoCallBack = ETrue ) = 0; |
|
187 |
|
188 // Print. |
|
189 /** |
|
190 * @brief Creates a print job in the specified printer. |
|
191 * @param[in] aDeviceID The ID of the printer where the client wishes to create the print job. |
|
192 * @param aImages Array containing the full names of the files to print. |
|
193 * @param aObserver The print event observer. |
|
194 * @return Any standard Symbian error code or ( KErrInvalidSequence and KErrInvalidData ). |
|
195 */ |
|
196 virtual TInt CreatePrintJobL( TInt aDeviceID, |
|
197 RPointerArray<TDesC>& aImages, |
|
198 MProtPrintEventObserver& aObserver ) = 0; |
|
199 /** |
|
200 * @brief Submits a print job already created. |
|
201 */ |
|
202 virtual void SubmitPrintJobL() = 0; |
|
203 /** |
|
204 * @brief Cancels the print job. |
|
205 */ |
|
206 virtual TInt CancelPrintJob() = 0; |
|
207 /** |
|
208 * @brief Continues printing and / or submitting a print job. Implementation may vary from protocol to protocol. |
|
209 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
210 */ |
|
211 virtual TInt ContinuePrintJobL() = 0; |
|
212 /** |
|
213 * @brief Gets the number of pages to be printed. |
|
214 * @return Number of pages to print. |
|
215 */ |
|
216 virtual TInt GetNumPrintPages() = 0; |
|
217 /** |
|
218 * DEPRECATED - DO NOT USE |
|
219 * @brief Gets the status of the printing job created. |
|
220 * @return Printing job status. |
|
221 */ |
|
222 virtual TInt GetPrintJobStatus() = 0; |
|
223 /** |
|
224 * DEPRECATED - DO NOT USE |
|
225 * @brief Gets the status of the printer. |
|
226 * @param[in] aDeviceID The ID of the printer the client wants to know about. |
|
227 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
228 */ |
|
229 virtual TInt GetPrinterStatus( TInt aDeviceID ) = 0; |
|
230 // Capabilities. |
|
231 /** |
|
232 * @brief Gets the IDs of the capabilities supported by the printer specified. |
|
233 * @param[in] aDeviceID The ID of the printer the client wants to know about. |
|
234 * @param[out] aCapabilityIDs Array containing the ID's of the capabilities of the specified printer. |
|
235 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
236 */ |
|
237 virtual TInt GetDeviceCapabilityIDsL( TInt aDeviceID, |
|
238 RArray<TInt>& aCapabilityIDs ) = 0; |
|
239 /** |
|
240 * @brief Gets the detail of a certain capability of a certain printer. |
|
241 * @param[in] aDeviceID The exposed ID of the printer the client wants to know about. |
|
242 * @param[in] aCapabilityID ID of the capability of interest. |
|
243 * @param[out] aCapability Capability information. |
|
244 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
245 */ |
|
246 virtual TInt GetDeviceCapabilityL( TInt aDeviceID, |
|
247 TInt aCapabilityID, |
|
248 TPrintCapability& aCapability ) = 0; |
|
249 /** |
|
250 * @brief Gets a setting (i.e., papersize selected) from an existing job. |
|
251 * @param[in] aCapabilityID ID of the capability of interest. |
|
252 * @param[out] aValue Capability value. |
|
253 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
254 */ |
|
255 virtual TInt GetJobSetting( TInt aCapabilityID, |
|
256 TInt& aValue ) = 0; |
|
257 /** |
|
258 * @brief Sets a print job setting. |
|
259 * @param[in] aCapabilityID ID of the capability of interest. |
|
260 * @param[in] aValue New capability value. |
|
261 * @param[out] aAffectedCapability ID of any affected capability. |
|
262 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
263 */ |
|
264 virtual TInt SetJobSettingL( TInt aCapabilityID, |
|
265 TInt aValue, |
|
266 TInt& aAffectedCapability ) = 0; |
|
267 // Preview. |
|
268 /** |
|
269 * DEPRECATED - DO NOT USE |
|
270 * @brief Gets the number of pages in the preview. |
|
271 * @return Number of pages in the preview. |
|
272 */ |
|
273 virtual TInt GetNumPreviewPages() = 0; |
|
274 /** |
|
275 * DEPRECATED - DO NOT USE |
|
276 * @brief Gets the icon representing a given layout or template. |
|
277 * @param[in] aTemplateID ID of the template / layout of interest. |
|
278 * @param[out] aFsBitmapHandle Handle to the appropriate bitmap. |
|
279 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
280 */ |
|
281 virtual TInt GetJobTemplateIconL( TInt aTemplateID, |
|
282 TInt& aFsBitmapHandle ) = 0; |
|
283 /** |
|
284 * DEPRECATED - DO NOT USE |
|
285 * @brief Creates a preview image. |
|
286 * @param[in] aPageNumber Page number to create preview image of. |
|
287 * @return Any standard Symbian error code or error codes [ KErrInvalidSequence (-50) / KErrInvalidData (-51) ]. |
|
288 */ |
|
289 virtual TInt CreatePreviewImage( TInt aPageNumber ) = 0; |
|
290 |
|
291 /** |
|
292 * @brief Destructor. |
|
293 */ |
|
294 virtual ~MProtPrintingDevice() {} |
|
295 |
|
296 |
|
297 /** |
|
298 * @brief Registers the IdleObserver to send idle event notifications |
|
299 * @param A pointer to an object implementing MIdleObserver interface that will be notified of events |
|
300 * @note In order to stop sending notifications, send NULL as the parameter. |
|
301 */ |
|
302 virtual void RegisterIdleObserver( MProtIdleObserver *aObserver ) = 0; |
|
303 |
|
304 |
|
305 /** |
|
306 * @brief Number of copies setter. Must be called after the print job is created but before |
|
307 * submission. Amount of array elements must be the same with the amount of image files |
|
308 * in the print job. Array elements must be greater than 0. |
|
309 * @param aNumsOfCopies number of copies array |
|
310 * @param aErr contains error code on return |
|
311 */ |
|
312 virtual void SetNumsOfCopiesL( const RArray<TInt>& aNumsOfCopies, |
|
313 TInt& aErr ) = 0; |
|
314 |
|
315 public: |
|
316 TUid iDtor_ID_Key; |
|
317 protected: |
|
318 /// Protocol API observer. |
|
319 MProtDiscoveryObserver* iDiscoveryObserver; |
|
320 /// Protocol API observer. |
|
321 MProtPrintEventObserver* iPrintEventObserver; |
|
322 }; |
|
323 |
|
324 #endif // MPROTPRINTINGDEVICE_H |
|
325 |
|
326 // End of File |
|