1/*
2 * Copyright (C) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup OH_Print
18 * @{
19 *
20 * @brief Provides the definition of the C interface for the print module.
21 *
22 * @syscap SystemCapability.Print.PrintFramework
23 *
24 * @since 12
25 * @version 1.0
26 */
27
28/**
29 * @file ohprint.h
30 *
31 * @brief Declares the APIs to discover and connect printers, print files from a printer,
32 *        query the list of the added printers and the printer information within it, and so on.
33 *
34 * @library libohprint.so
35 * @syscap SystemCapability.Print.PrintFramework
36 * @since 12
37 * @version 1.0
38 */
39
40#ifndef OH_PRINT_H
41#define OH_PRINT_H
42
43#include <stdint.h>
44#include <stdbool.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/**
51 * @brief Defines error codes.
52 *
53 * @since 12
54 * @version 1.0
55 */
56typedef enum {
57    /** @error The operation is successful. */
58    PRINT_ERROR_NONE = 0,
59    /** @error Permission verification failed. */
60    PRINT_ERROR_NO_PERMISSION = 201,
61    /** @error Invalid parameter. */
62    PRINT_ERROR_INVALID_PARAMETER = 401,
63    /** @error General internal error. */
64    PRINT_ERROR_GENERIC_FAILURE = 24300001,
65    /** @error RPC communication error. */
66    PRINT_ERROR_RPC_FAILURE = 24300002,
67    /** @error Server error. */
68    PRINT_ERROR_SERVER_FAILURE = 24300003,
69    /** @error Invalid extension. */
70    PRINT_ERROR_INVALID_EXTENSION = 24300004,
71    /** @error Invalid printer. */
72    PRINT_ERROR_INVALID_PRINTER = 24300005,
73    /** @error Invalid print job. */
74    PRINT_ERROR_INVALID_PRINT_JOB = 24300006,
75    /** @error Failed to read or write files. */
76    PRINT_ERROR_FILE_IO = 24300007,
77    /** @error Unknown error. */
78    PRINT_ERROR_UNKNOWN = 24300255,
79} Print_ErrorCode;
80
81/**
82 * @brief Indicates printer states.
83 *
84 * @since 12
85 */
86typedef enum {
87    /** Printer idle. */
88    PRINTER_IDLE,
89    /** Printer busy. */
90    PRINTER_BUSY,
91    /** Printer not available. */
92    PRINTER_UNAVAILABLE,
93} Print_PrinterState;
94
95/**
96 * @brief Indicate printer discovery events.
97 *
98 * @since 12
99 */
100typedef enum {
101    /** Printer discovered. */
102    PRINTER_DISCOVERED = 0,
103    /** Printer lost. */
104    PRINTER_LOST = 1,
105    /** Printer connecting. */
106    PRINTER_CONNECTING = 2,
107    /** Printer connected. */
108    PRINTER_CONNECTED = 3,
109} Print_DiscoveryEvent;
110
111/**
112 * @brief Indicate printer change events.
113 *
114 * @since 12
115 */
116typedef enum {
117    /** Printer added. */
118    PRINTER_ADDED = 0,
119    /** Printer deleted. */
120    PRINTER_DELETED = 1,
121    /** Printer state changed. */
122    PRINTER_STATE_CHANGED = 2,
123    /** Printer info changed. */
124    PRINTER_INFO_CHANGED = 3,
125    /** Printer preference changed. */
126    PRINTER_PREFERENCE_CHANGED = 4,
127} Print_PrinterEvent;
128
129/**
130 * @brief Indicates string list.
131 *
132 * @since 12
133 */
134typedef struct {
135    /** Number of string. */
136    uint32_t count;
137    /** String pointer array. */
138    char **list;
139} Print_StringList;
140
141/**
142 * @brief Indicates printer property.
143 *
144 * @since 12
145 */
146typedef struct {
147    /** Property keyword. */
148    char *key;
149    /** Property value. */
150    char *value;
151} Print_Property;
152
153/**
154 * @brief List of printer properties.
155 *
156 * @since 12
157 */
158typedef struct {
159    /** Number of properties. */
160    uint32_t count;
161    /** Property pointer array. */
162    Print_Property *list;
163} Print_PropertyList;
164
165/**
166 * @brief Indicates print resolution in dpi unit.
167 *
168 * @since 12
169 */
170typedef struct {
171    uint32_t horizontalDpi;
172    uint32_t verticalDpi;
173} Print_Resolution;
174
175/**
176 * @brief Indicates printing margin
177 *
178 * @since 12
179 */
180typedef struct {
181    /** Left margin. */
182    uint32_t leftMargin;
183    /** Top margin. */
184    uint32_t topMargin;
185    /** Right margin. */
186    uint32_t rightMargin;
187    /** Bottom margin. */
188    uint32_t bottomMargin;
189} Print_Margin;
190
191/**
192 * @brief Indicates paper size info.
193 *
194 * @since 12
195 */
196typedef struct {
197    /** Paper id. */
198    char *id;
199    /** Paper name. */
200    char *name;
201    /** Paper width. */
202    uint32_t width;
203    /** Paper height. */
204    uint32_t height;
205} Print_PageSize;
206
207/**
208 * @brief Indicates DuplexMode
209 *
210 * @since 12
211 */
212typedef enum {
213    /** One sided duplex mode. */
214    DUPLEX_MODE_ONE_SIDED = 0,
215    /** Long edge two sided duplex mode. */
216    DUPLEX_MODE_TWO_SIDED_LONG_EDGE = 1,
217    /** Short edge two sided duplex mode. */
218    DUPLEX_MODE_TWO_SIDED_SHORT_EDGE = 2,
219} Print_DuplexMode;
220
221/**
222 * @brief Indicates ColorMode
223 *
224 * @since 12
225 */
226typedef enum {
227    /** Monochrome mode. */
228    COLOR_MODE_MONOCHROME = 0,
229    /** Color mode. */
230    COLOR_MODE_COLOR = 1,
231    /** Auto mode. */
232    COLOR_MODE_AUTO = 2,
233} Print_ColorMode;
234
235/**
236 * @brief Indicates OrientationMode
237 *
238 * @since 12
239 */
240typedef enum {
241    /** Portrait mode. */
242    ORIENTATION_MODE_PORTRAIT = 0,
243    /** Landscape mode. */
244    ORIENTATION_MODE_LANDSCAPE = 1,
245    /** Reverse landscape mode. */
246    ORIENTATION_MODE_REVERSE_LANDSCAPE = 2,
247    /** Reverse portrait mode. */
248    ORIENTATION_MODE_REVERSE_PORTRAIT = 3,
249    /** Not specified. */
250    ORIENTATION_MODE_NONE = 4,
251} Print_OrientationMode;
252
253/**
254 * @brief Indicates printing qulity
255 *
256 * @since 12
257 */
258typedef enum {
259    /** Draft quality mode */
260    PRINT_QUALITY_DRAFT = 3,
261    /** Normal quality mode */
262    PRINT_QUALITY_NORMAL = 4,
263    /** High quality mode */
264    PRINT_QUALITY_HIGH = 5
265} Print_Quality;
266
267/**
268 * @brief Indicates the MIME media type of the document.
269 *
270 * @since 12
271 */
272typedef enum {
273    /** MIME: application/octet-stream. */
274    DOCUMENT_FORMAT_AUTO,
275    /** MIME: image/jpeg. */
276    DOCUMENT_FORMAT_JPEG,
277    /** MIME: application/pdf. */
278    DOCUMENT_FORMAT_PDF,
279    /** MIME: application/postscript. */
280    DOCUMENT_FORMAT_POSTSCRIPT,
281    /** MIME: text/plain. */
282    DOCUMENT_FORMAT_TEXT,
283} Print_DocumentFormat;
284
285/**
286 * @brief Indicates the print job doc adapter state.
287 *
288 * @since 13
289 */
290typedef enum {
291    /** Print job preview ability destroy. */
292    PRINT_DOC_ADAPTER_PREVIEW_ABILITY_DESTROY = 0,
293    /** Print job task succeed. */
294    PRINT_DOC_ADAPTER_PRINT_TASK_SUCCEED = 1,
295    /** Print job task failed. */
296    PRINT_DOC_ADAPTER_PRINT_TASK_FAIL = 2,
297    /** Print job task cancel. */
298    PRINT_DOC_ADAPTER_PRINT_TASK_CANCEL = 3,
299    /** Print job task block. */
300    PRINT_DOC_ADAPTER_PRINT_TASK_BLOCK = 4,
301    /** Print job task preview ability destroy for canceled. */
302    PRINT_DOC_ADAPTER_PREVIEW_ABILITY_DESTROY_FOR_CANCELED = 5,
303    /** Print job task preview ability destroy for started. */
304    PRINT_DOC_ADAPTER_PREVIEW_ABILITY_DESTROY_FOR_STARTED = 6,
305} Print_JobDocAdapterState;
306
307/**
308 * @brief Indicates printer capabilities.
309 *
310 * @since 12
311 */
312typedef struct {
313    /** Array of supported color mode. */
314    Print_ColorMode *supportedColorModes;
315    /** Number of supported color mode. */
316    uint32_t supportedColorModesCount;
317    /** Array of supported duplex printing modes. */
318    Print_DuplexMode *supportedDuplexModes;
319    /** Number of supported duplex printing mode. */
320    uint32_t supportedDuplexModesCount;
321    /** Array of supported print paper sizes. */
322    Print_PageSize *supportedPageSizes;
323    /** Number of supported print paper sizes. */
324    uint32_t supportedPageSizesCount;
325    /** Supported print media types in json string array format. */
326    char *supportedMediaTypes;
327    /** Array of supported print qulities. */
328    Print_Quality *supportedQualities;
329    /** Number of supported print qulities. */
330    uint32_t supportedQualitiesCount;
331    /** Supported paper sources in json string array format. */
332    char *supportedPaperSources;
333    /** Supported copies. */
334    uint32_t supportedCopies;
335    /** Array of supported printer resolutions. */
336    Print_Resolution *supportedResolutions;
337    /** Number of supported printer resolutions. */
338    uint32_t supportedResolutionsCount;
339    /** Array of supported orientation. */
340    Print_OrientationMode *supportedOrientations;
341    /** Number of supported orientation. */
342    uint32_t supportedOrientationsCount;
343    /** Advanced capability in json format. */
344    char *advancedCapability;
345} Print_PrinterCapability;
346
347/**
348 * @brief Indicates current properties
349 *
350 * @since 12
351 */
352typedef struct {
353    /** Default color mode. */
354    Print_ColorMode defaultColorMode;
355    /** Default duplex mode. */
356    Print_DuplexMode defaultDuplexMode;
357    /** Default media type. */
358    char *defaultMediaType;
359    /** Default page size id. */
360    char *defaultPageSizeId;
361    /** Default margin. */
362    Print_Margin defaultMargin;
363    /** Default paper source. */
364    char *defaultPaperSource;
365    /** Default print quality */
366    Print_Quality defaultPrintQuality;
367    /** Default copies. */
368    uint32_t defaultCopies;
369    /** Default printer resolution. */
370    Print_Resolution defaultResolution;
371    /** Default orientation. */
372    Print_OrientationMode defaultOrientation;
373    /** Other default values in json format. */
374    char *otherDefaultValues;
375} Print_DefaultValue;
376
377/**
378 * @brief Indicates printer information.
379 *
380 * @since 12
381 */
382typedef struct {
383    /** Printer state. */
384    Print_PrinterState printerState;
385    /** Printer capabilities. */
386    Print_PrinterCapability capability;
387    /** Printer current properties. */
388    Print_DefaultValue defaultValue;
389    /** Default printer. */
390    bool isDefaultPrinter;
391    /** Printer id. */
392    char *printerId;
393    /** Printer name. */
394    char *printerName;
395    /** Printer description. */
396    char *description;
397    /** Printer location. */
398    char *location;
399    /** Printer make and model information. */
400    char *makeAndModel;
401    /** Printer Uri. */
402    char *printerUri;
403    /** Detail information in json format. */
404    char *detailInfo;
405} Print_PrinterInfo;
406
407/**
408 * @brief Indicates PrintJob Structure.
409 *
410 * @since 12
411 */
412typedef struct {
413    /** Job name. */
414    char *jobName;
415    /** Array of file descriptors to print. */
416    uint32_t *fdList;
417    /** Number of file descriptors to print. */
418    uint32_t fdListCount;
419    /** Printer id. */
420    char *printerId;
421    /** Number of copies printed. */
422    uint32_t copyNumber;
423    /** Paper source. */
424    char *paperSource;
425    /** Media type. */
426    char *mediaType;
427    /** Paper size id. */
428    char *pageSizeId;
429    /** Color mode. */
430    Print_ColorMode colorMode;
431    /** Duplex source. */
432    Print_DuplexMode duplexMode;
433    /** Print resolution in dpi. */
434    Print_Resolution resolution;
435    /** Print margin. */
436    Print_Margin printMargin;
437    /** Borderless. */
438    bool borderless;
439    /** Orientation mode. */
440    Print_OrientationMode orientationMode;
441    /** Print quality. */
442    Print_Quality printQuality;
443    /** Document format. */
444    Print_DocumentFormat documentFormat;
445    /** Advanced options in json format. */
446    char *advancedOptions;
447} Print_PrintJob;
448
449/**
450 * @brief Indicates print range structure.
451 *
452 * @since 13
453 */
454typedef struct {
455    /** Print start page. */
456    uint32_t startPage;
457    /** Print end page. */
458    uint32_t endPage;
459    /** Print page array length. */
460    uint32_t pagesArrayLen;
461    /** Print page array. */
462    uint32_t* pagesArray;
463} Print_Range;
464
465/**
466 * @brief Indicates print attributes structure.
467 *
468 * @since 13
469 */
470typedef struct {
471    /** Print ranges. */
472    Print_Range pageRange;
473    /** Print page size. */
474    Print_PageSize pageSize;
475    /** Print margin. */
476    Print_Margin pageMargin;
477    /** Copy numbers. */
478    uint32_t copyNumber;
479    /** Duplex mode. */
480    uint32_t duplexMode;
481    /** Color mode. */
482    uint32_t colorMode;
483    /** Print sequential. */
484    bool isSequential;
485    /** Print orient. */
486    bool isLandscape;
487    /** Print option flag. */
488    bool hasOption;
489    /** Print options. */
490    char options[256];
491} Print_PrintAttributes;
492
493/**
494 * @brief Write files result callback.
495 *
496 * @param jobId The print job id of one print task.
497 * @param code The result of write files.
498 * @since 13
499 */
500typedef void(*Print_WriteResultCallback)(const char *jobId, uint32_t code);
501
502/**
503 * @brief Print start layout callback.
504 *
505 * @param jobId The print job id of one print task.
506 * @param fd The file descriptor to be written.
507 * @param oldAttrs The attributes of last.
508 * @param newAttrs The attributes of current.
509 * @param writeCallback The Write files result callback.
510 * @since 13
511 */
512typedef void(*Print_OnStartLayoutWrite)(const char *jobId,
513                                        uint32_t fd,
514                                        const Print_PrintAttributes *oldAttrs,
515                                        const Print_PrintAttributes *newAttrs,
516                                        Print_WriteResultCallback writeCallback);
517
518/**
519 * @brief Print job state callback.
520 *
521 * @param jobId The print job id of one print task.
522 * @param state The state of current print job.
523 * @since 13
524 */
525typedef void(*Print_OnJobStateChanged)(const char *jobId, uint32_t state);
526
527/**
528 * @brief Indicates print doc state callback structure.
529 *
530 * @since 13
531 */
532typedef struct {
533    /** Print start layout callback. */
534    Print_OnStartLayoutWrite startLayoutWriteCb;
535    /** Print job state callback. */
536    Print_OnJobStateChanged jobStateChangedCb;
537} Print_PrintDocCallback;
538
539/**
540 * @brief Printer discovery callback.
541 *
542 * @param event The printer discovery event during printer discovery.
543 * @param printerInfo The printer infomation at the time of the discovery event.
544 * @since 12
545 */
546typedef void (*Print_PrinterDiscoveryCallback)(Print_DiscoveryEvent event, const Print_PrinterInfo *printerInfo);
547
548/**
549 * @brief Printer change callback.
550 *
551 * @param event The printer change event while the printer service is running.
552 * @param printerInfo The printer infomation at the time of the change event.
553 * @since 12
554 */
555typedef void (*Print_PrinterChangeCallback)(Print_PrinterEvent event, const Print_PrinterInfo *printerInfo);
556
557/**
558 * @brief This API checks and pulls up the print service, initializes the print client,
559 *        and establishes a connection to the print service.
560 *
561 * @permission {@code ohos.permission.PRINT}
562 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
563 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
564 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
565 *         {@link PRINT_ERROR_SERVER_FAILURE} The cups service cannot be started.
566 * @syscap SystemCapability.Print.PrintFramework
567 * @since 12
568 */
569Print_ErrorCode OH_Print_Init();
570
571/**
572 * @brief This API closes the connection from the print service, dissolves the previous callback,
573 *        and releases the print client resources.
574 *
575 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
576 *         Currently no other error codes will be returned.
577 * @syscap SystemCapability.Print.PrintFramework
578 * @since 12
579 */
580Print_ErrorCode OH_Print_Release();
581
582/**
583 * @brief This API starts discovering printers.
584 *
585 * @permission {@code ohos.permission.PRINT}
586 * @param callback The {@link Print_PrinterDiscoveryCallback} of printer discovery event.
587 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
588 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
589 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
590 *         {@link PRINT_ERROR_SERVER_FAILURE} Failed to query print extension list from BMS.
591 *         {@link PRINT_ERROR_INVALID_EXTENSION} No available print extensions found.
592 * @syscap SystemCapability.Print.PrintFramework
593 * @since 12
594 */
595Print_ErrorCode OH_Print_StartPrinterDiscovery(Print_PrinterDiscoveryCallback callback);
596
597/**
598 * @brief This API stops discovering printers.
599 *
600 * @permission {@code ohos.permission.PRINT}
601 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
602 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
603 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
604 * @syscap SystemCapability.Print.PrintFramework
605 * @since 12
606 */
607Print_ErrorCode OH_Print_StopPrinterDiscovery();
608
609/**
610 * @brief This API connects to the printer using the printer id.
611 *
612 * @permission {@code ohos.permission.PRINT}
613 * @param printerId The id of the printer to be connected.
614 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
615 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
616 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
617 *         {@link PRINT_ERROR_INVALID_PRINTER} The printer should be in the list of discovered printers.
618 *         {@link PRINT_ERROR_SERVER_FAILURE} Unable to find an extension responsible for the printer.
619 * @syscap SystemCapability.Print.PrintFramework
620 * @since 12
621 */
622Print_ErrorCode OH_Print_ConnectPrinter(const char *printerId);
623
624/**
625 * @brief This API starts initiating a print job.
626 *
627 * @permission {@code ohos.permission.PRINT}
628 * @param printJob A pointer to a {@link Print_PrintJob} instance that specifies the information for the print job.
629 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
630 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
631 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
632 *         {@link PRINT_ERROR_INVALID_PRINTER} The printer should be in the list of connected printers.
633 *         {@link PRINT_ERROR_SERVER_FAILURE} Unable to create print job in the print service.
634 *         {@link PRINT_ERROR_INVALID_PRINT_JOB} Unable to find the job int the job queue.
635 * @syscap SystemCapability.Print.PrintFramework
636 * @since 12
637 */
638Print_ErrorCode OH_Print_StartPrintJob(const Print_PrintJob *printJob);
639
640/**
641 * @brief This API registers the callback for printer changes.
642 *
643 * @permission {@code ohos.permission.PRINT}
644 * @param callback The {@link Print_PrinterChangeCallback} to be registered.
645 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
646 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
647 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
648 * @syscap SystemCapability.Print.PrintFramework
649 * @since 12
650 */
651Print_ErrorCode OH_Print_RegisterPrinterChangeListener(Print_PrinterChangeCallback callback);
652
653/**
654 * @brief This API unregisters the callback for printer changes.
655 *
656 * @permission {@code ohos.permission.PRINT}
657 * @syscap SystemCapability.Print.PrintFramework
658 * @since 12
659 */
660void OH_Print_UnregisterPrinterChangeListener();
661
662/**
663 * @brief This API queries for a list of added printers.
664 *
665 * @permission {@code ohos.permission.PRINT}
666 * @param printerIdList A pointer to a {@link Print_StringList} instance to store the queried printer id list.
667 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
668 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
669 *         {@link PRINT_ERROR_INVALID_PARAMETER} printerIdList is NULL.
670 *         {@link PRINT_ERROR_INVALID_PRINTER} Unable to query any connected printers.
671 *         {@link PRINT_ERROR_GENERIC_FAILURE} Unable to copy the printer id list.
672 * @syscap SystemCapability.Print.PrintFramework
673 * @since 12
674 */
675Print_ErrorCode OH_Print_QueryPrinterList(Print_StringList *printerIdList);
676
677/**
678 * @brief This API frees up the printer list memory for the query.
679 *
680 * @param printerIdList The queried printer id list to be released.
681 * @syscap SystemCapability.Print.PrintFramework
682 * @since 12
683 */
684void OH_Print_ReleasePrinterList(Print_StringList *printerIdList);
685
686/**
687 * @brief This API queries printer information based on the printer id.
688 *
689 * @permission {@code ohos.permission.PRINT}
690 * @param printerId The id of the printer to be queried.
691 * @param printerInfo A pointer to a {@link Print_PrinterInfo} pointer to store the printer infomation.
692 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
693 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
694 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
695 *         {@link PRINT_ERROR_INVALID_PARAMETER} printerId is NULL or printerInfo is NULL.
696 *         {@link PRINT_ERROR_INVALID_PRINTER} Unable to find the printer in the connected printer list.
697 * @syscap SystemCapability.Print.PrintFramework
698 * @since 12
699 */
700Print_ErrorCode OH_Print_QueryPrinterInfo(const char *printerId, Print_PrinterInfo **printerInfo);
701
702/**
703 * @brief This API frees up the printer infomation memory for the query.
704 *
705 * @param printerInfo The pointer of the queried printer infomation to be released.
706 * @syscap SystemCapability.Print.PrintFramework
707 * @since 12
708 */
709void OH_Print_ReleasePrinterInfo(Print_PrinterInfo *printerInfo);
710
711/**
712 * @brief This API launches the system's printer management window.
713 *
714 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
715 *         {@link PRINT_ERROR_GENERIC_FAILURE} Unable to launch the printer manager window.
716 * @syscap SystemCapability.Print.PrintFramework
717 * @since 12
718 */
719Print_ErrorCode OH_Print_LaunchPrinterManager();
720
721/**
722 * @brief This API queries the corresponding printer property values based on the list of property keywords.
723 *
724 * @permission {@code ohos.permission.PRINT}
725 * @param printerId The id of the printer to be queried.
726 * @param propertyKeyList The list of property keywords to be queried
727 * @param propertyList The list of printer property values queried.
728 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
729 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
730 *         {@link PRINT_ERROR_INVALID_PARAMETER} One of the params is NULL or the keyword list is empty.
731 *         {@link PRINT_ERROR_INVALID_PRINTER} The printer properties for the specified printer could not be found.
732 *         {@link PRINT_ERROR_GENERIC_FAILURE} Unable to copy the printer properties.
733 * @syscap SystemCapability.Print.PrintFramework
734 * @since 12
735 */
736Print_ErrorCode OH_Print_QueryPrinterProperties(const char *printerId, const Print_StringList *propertyKeyList,
737    Print_PropertyList *propertyList);
738
739/**
740 * @brief This API frees up the property list memory for the query.
741 *
742 * @param propertyList The pointer of the queried printer property values to be released.
743 * @syscap SystemCapability.Print.PrintFramework
744 * @since 12
745 */
746void OH_Print_ReleasePrinterProperties(Print_PropertyList *propertyList);
747
748/**
749 * @brief This API sets printer properties based on a list of property key-value pairs.
750 *
751 * @permission {@code ohos.permission.PRINT}
752 * @param printerId The id of the printer to be set.
753 * @param propertyList The list of printer property values to be set.
754 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
755 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
756 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
757 * @syscap SystemCapability.Print.PrintFramework
758 * @since 12
759 */
760Print_ErrorCode OH_Print_UpdatePrinterProperties(const char *printerId, const Print_PropertyList *propertyList);
761
762/**
763 * @brief This API restores printer properties to default settings based on the list of property keywords.
764 *
765 * @permission {@code ohos.permission.PRINT}
766 * @param printerId The id of the printer to be restored.
767 * @param propertyKeyList The list of property keywords to be restored.
768 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
769 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
770 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
771 * @syscap SystemCapability.Print.PrintFramework
772 * @since 12
773 */
774Print_ErrorCode OH_Print_RestorePrinterProperties(const char *printerId, const Print_StringList *propertyKeyList);
775
776/**
777 * @brief This API provides capacity to start print service.
778 *
779 * @permission {@code ohos.permission.PRINT}
780 * @param printJobName The name of this print job.
781 * @param printDocCallback The print doc state callback.
782 * @param context The context of caller app.
783 * @return Returns {@link Print_ErrorCode#PRINT_ERROR_NONE} if the execution is successful.
784 *         {@link PRINT_ERROR_NO_PERMISSION} The permission {@code ohos.permission.PRINT} is needed.
785 *         {@link PRINT_ERROR_RPC_FAILURE} Unable to connect to the print service.
786 * @syscap SystemCapability.Print.PrintFramework
787 * @since 13
788 */
789Print_ErrorCode OH_Print_StartPrintByNative(const char *printJobName,
790                                            Print_PrintDocCallback printDocCallback,
791                                            void *context);
792
793#ifdef __cplusplus
794}
795#endif
796
797#endif // OH_PRINT_H
798/** @} */
799