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