1# @ohos.app.ability.PrintExtensionAbility (Print Extension Ability) (System API)
2
3The **PrintExtensionAbility** module provides operation APIs of the print extension ability.
4
5> **NOTE**
6> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
7>
8> The APIs provided by this module are system APIs.
9>
10> The APIs of this module can be used only in the stage model.
11
12## Modules to Import
13
14```ts
15import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
16```
17
18## onCreate
19
20onCreate(want: Want): void
21
22Called to initialize the print extension when the system connects to the extension for the first time.
23
24**System capability**: SystemCapability.Print.PrintFramework
25
26**Parameters**
27| **Name**| **Type**| **Mandatory**| **Description**|
28| -------- | -------- | -------- | -------- |
29| want | Want | Yes| Parameters required for invoking the print page.|
30
31**Error codes**
32
33For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
34
35| ID| Error Message                                   |
36| -------- | ------------------------------------------- |
37| 202 | Permission verification failed. A non-system application calls a system API. |
38
39**Example**
40
41```ts
42import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
43import Want from '@ohos.app.ability.Want';
44
45export default class HWPrintExtension extends PrintExtensionAbility {
46    onCreate(want: Want): void {
47        console.log('onCreate');
48        // ...
49    }
50}
51```
52
53## onStartDiscoverPrinter
54
55onStartDiscoverPrinter(): void
56
57Called when an attempt to discover printers starts.
58
59**System capability**: SystemCapability.Print.PrintFramework
60
61**Error codes**
62
63For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
64
65| ID| Error Message                                   |
66| -------- | ------------------------------------------- |
67| 202 | Permission verification failed. A non-system application calls a system API. |
68
69**Example**
70
71```ts
72import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
73
74export default class HWPrintExtension extends PrintExtensionAbility {
75    onStartDiscoverPrinter(): void {
76        console.log('onStartDiscoverPrinter enter');
77        // ...
78    }
79}
80```
81
82## onStopDiscoverPrinter
83
84onStopDiscoverPrinter(): void
85
86Called when the attempt to discover printers stops.
87
88**System capability**: SystemCapability.Print.PrintFramework
89
90**Error codes**
91
92For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
93
94| ID| Error Message                                   |
95| -------- | ------------------------------------------- |
96| 202 | Permission verification failed. A non-system application calls a system API. |
97
98**Example**
99
100```ts
101import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
102
103export default class HWPrintExtension extends PrintExtensionAbility {
104    onStopDiscoverPrinter(): void {
105        console.log('onStopDiscoverPrinter enter');
106        // ...
107    }
108}
109```
110
111## onConnectPrinter
112
113onConnectPrinter(printerId: number): void
114
115Called when the device connects to the specified printer.
116
117**System capability**: SystemCapability.Print.PrintFramework
118
119**Parameters**
120| **Name**| **Type**| **Mandatory**| **Description**|
121| -------- | -------- | -------- | -------- |
122| printerId | number | Yes| Printer ID.|
123
124**Error codes**
125
126For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
127
128| ID| Error Message                                   |
129| -------- | ------------------------------------------- |
130| 202 | Permission verification failed. A non-system application calls a system API. |
131
132**Example**
133
134```ts
135import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
136
137export default class HWPrintExtension extends PrintExtensionAbility {
138    onConnectPrinter(printerId: number): void {
139        console.log('onConnectPrinter enter');
140        // ...
141    }
142}
143```
144
145## onDisconnectPrinter
146
147onDisconnectPrinter(printerId: number): void
148
149Called when the device disconnects from the specified printer.
150
151**System capability**: SystemCapability.Print.PrintFramework
152
153**Parameters**
154| **Name**| **Type**| **Mandatory**| **Description**|
155| -------- | -------- | -------- | -------- |
156| printerId | number | Yes| Printer ID.|
157
158**Error codes**
159
160For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
161
162| ID| Error Message                                   |
163| -------- | ------------------------------------------- |
164| 202 | Permission verification failed. A non-system application calls a system API. |
165
166**Example**
167
168```ts
169import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
170
171export default class HWPrintExtension extends PrintExtensionAbility {
172    onDisconnectPrinter(printerId: number): void {
173        console.log('onDisconnectPrinter enter');
174        // ...
175    }
176}
177```
178
179## onStartPrintJob
180
181onStartPrintJob(jobInfo: print.PrintJob): void
182
183Called when the specified print job starts.
184
185**System capability**: SystemCapability.Print.PrintFramework
186
187**Parameters**
188| **Name**| **Type**| **Mandatory**| **Description**|
189| -------- | -------- | -------- | -------- |
190| jobInfo | print.PrintJob | Yes| Information about the print job.|
191
192**Error codes**
193
194For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
195
196| ID| Error Message                                   |
197| -------- | ------------------------------------------- |
198| 202 | Permission verification failed. A non-system application calls a system API. |
199
200**Example**
201
202```ts
203import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
204import print from '@ohos.print';
205
206export default class HWPrintExtension extends PrintExtensionAbility {
207    onStartPrintJob(jobInfo: print.PrintJob): void {
208        console.log('onStartPrintJob, jobId is: ' + jobInfo.jobId);
209        // ...
210    }
211}
212```
213
214## onCancelPrintJob
215
216onCancelPrintJob(jobInfo: print.PrintJob): void
217
218Called when the specified print job is canceled.
219
220**System capability**: SystemCapability.Print.PrintFramework
221
222**Parameters**
223| **Name**| **Type**| **Mandatory**| **Description**|
224| -------- | -------- | -------- | -------- |
225| jobInfo | print.PrintJob | Yes| Information about the print job.|
226
227**Error codes**
228
229For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
230
231| ID| Error Message                                   |
232| -------- | ------------------------------------------- |
233| 202 | Permission verification failed. A non-system application calls a system API. |
234
235**Example**
236
237```ts
238import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
239import print from '@ohos.print';
240
241export default class HWPrintExtension extends PrintExtensionAbility {
242    onCancelPrintJob(jobInfo: print.PrintJob): void {
243        console.log('onCancelPrintJob, jobId is: ' + jobInfo.jobId);
244        // ...
245    }
246}
247```
248
249## onRequestPrinterCapability
250
251onRequestPrinterCapability(printerId: number): print.PrinterCapability
252
253Called when a request is sent to check the capability of the specified printer.
254
255**System capability**: SystemCapability.Print.PrintFramework
256
257**Parameters**
258| **Name**| **Type**| **Mandatory**| **Description**|
259| -------- | -------- | -------- | -------- |
260| printerId | number | Yes| Printer ID.|
261
262**Return value**
263| **Type**| **Description**|
264| -------- | -------- |
265| print.PrinterCapability | Capability of the printer.|
266
267**Error codes**
268
269For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
270
271| ID| Error Message                                   |
272| -------- | ------------------------------------------- |
273| 202 | Permission verification failed. A non-system application calls a system API. |
274
275**Example**
276
277```ts
278import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
279import print from '@ohos.print';
280
281export default class HWPrintExtension extends PrintExtensionAbility {
282    onRequestPrinterCapability(printerId: number): print.PrinterCapability {
283        console.log('onRequestPrinterCapability enter');
284        // ...
285        let tmp : print.PrinterCapability = {
286            colorMode : 1,
287            duplexMode : 1,
288            pageSize : []
289        };
290        return tmp;
291    }
292}
293```
294
295## onRequestPreview
296
297onRequestPreview(jobInfo: print.PrintJob): string
298
299Called when a print preview request is sent. The result is returned to the print SA.
300
301**System capability**: SystemCapability.Print.PrintFramework
302
303**Parameters**
304| **Name**| **Type**| **Mandatory**| **Description**|
305| -------- | -------- | -------- | -------- |
306| jobInfo | print.PrintJob | Yes| Information about the print job.|
307
308**Return value**
309| **Type**| **Description**|
310| -------- | -------- |
311| string | Preview result.|
312
313**Error codes**
314
315For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
316
317| ID| Error Message                                   |
318| -------- | ------------------------------------------- |
319| 202 | Permission verification failed. A non-system application calls a system API. |
320
321**Example**
322
323```ts
324import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
325import print from '@ohos.print';
326
327export default class HWPrintExtension extends PrintExtensionAbility {
328    onRequestPreview(jobInfo: print.PrintJob): string {
329        console.log('onRequestPreview enter');
330        // ...
331        let tmp : string = '';
332        return tmp;
333    }
334}
335```
336
337## onDestroy
338
339onDestroy(): void
340
341Called when the print extension ability is stopped.
342
343**System capability**: SystemCapability.Print.PrintFramework
344
345**Error codes**
346
347For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md).
348
349| ID| Error Message                                   |
350| -------- | ------------------------------------------- |
351| 202 | Permission verification failed. A non-system application calls a system API. |
352
353**Example**
354
355```ts
356import PrintExtensionAbility from '@ohos.app.ability.PrintExtensionAbility';
357
358export default class HWPrintExtension extends PrintExtensionAbility {
359    onDestroy(): void {
360        console.log('onDestroy');
361    }
362}
363```
364