libwkhtmltox
Typedefs | Functions | Variables
pdf.h File Reference

Provides C bindings for pdf conversion. More...

#include <wkhtmltox/dllbegin.inc>
#include <wkhtmltox/dllend.inc>

Typedefs

typedef struct wkhtmltopdf_global_settings wkhtmltopdf_global_settings
 
typedef struct wkhtmltopdf_object_settings wkhtmltopdf_object_settings
 
typedef struct wkhtmltopdf_converter wkhtmltopdf_converter
 
typedef void(* wkhtmltopdf_str_callback) (wkhtmltopdf_converter *converter, const char *str)
 Function pointer type used for the error and warning callbacks. More...
 
typedef void(* wkhtmltopdf_int_callback) (wkhtmltopdf_converter *converter, const int val)
 Function pointer type used for the progress_changed and finished callbacks. More...
 
typedef void(* wkhtmltopdf_void_callback) (wkhtmltopdf_converter *converter)
 Function pointer type used for the phase_changed callback. More...
 

Functions

 CAPI (int) wkhtmltopdf_init(int use_graphics)
 Setup wkhtmltopdf. More...
 
 CAPI (const char *) wkhtmltopdf_version()
 Return a short utf8 description of a conversion phase. More...
 
 CAPI (wkhtmltopdf_global_settings *) wkhtmltopdf_create_global_settings()
 Create a new global settings object for pdf conversion. More...
 
 CAPI (void) wkhtmltopdf_destroy_global_settings(wkhtmltopdf_global_settings *)
 Destroy a global settings object. More...
 
 CAPI (wkhtmltopdf_object_settings *) wkhtmltopdf_create_object_settings()
 Create an object used to store object settings. More...
 
 CAPI (wkhtmltopdf_converter *) wkhtmltopdf_create_converter(wkhtmltopdf_global_settings *settings)
 Create a wkhtmltopdf converter object. More...
 
 CAPI (long) wkhtmltopdf_get_output(wkhtmltopdf_converter *converter
 

Variables

const char * name
 
const char const char * value
 
const char char int vs
 
wkhtmltopdf_str_callback cb
 
wkhtmltopdf_object_settingssetting
 
wkhtmltopdf_object_settings const char * data
 
int phase
 

Detailed Description

Provides C bindings for pdf conversion.

Typedef Documentation

◆ wkhtmltopdf_int_callback

wkhtmltopdf_int_callback

Function pointer type used for the progress_changed and finished callbacks.

For the progress_changed callback the value indicated the progress within the current phase in percent. For the finished callback the value if 1 if the conversion has successful and 0 otherwise.

Parameters
converterThe converter that issued the callback
valThe integer value
See also
wkhtmltopdf_set_progress_changed, wkhtmltopdf_set_finished_callback

◆ wkhtmltopdf_str_callback

wkhtmltopdf_str_callback

Function pointer type used for the error and warning callbacks.

Parameters
converterThe converter that issued the callback
strA utf8 encoded string containing the error or warning message.
See also
wkhtmltopdf_set_error_callback, wkhtmltopdf_set_warning_callback

◆ wkhtmltopdf_void_callback

wkhtmltopdf_void_callback

Function pointer type used for the phase_changed callback.

Parameters
converterThe converter that issued the callback
See also
wkhtmltopdf_set_phase_changed_callback

Function Documentation

◆ CAPI() [1/6]

CAPI ( const char *  )

Return a short utf8 description of a conversion phase.

Return a short utf8 string indicating progress within a phase.

Parameters
converterThe converter to query
phaseThe number of the conversion step of which we want a description
Returns
A description of the conversion phase
See also
wkhtmltopdf_current_phase, wkhtmltopdf_phase_description

Will typically return a string like "40%"

Parameters
converterThe converter to query
Returns
A string containing a progress indication
See also
wkhtmltopdf_set_progress_changed_callback

◆ CAPI() [2/6]

CAPI ( int  )

Setup wkhtmltopdf.

Return the largest HTTP error code encountered during conversion.

Get the total number of phases the conversion process will go trough.

Get the number of the current conversion phase.

Convert the input objects into a pdf document.

Retrieve a setting in a object settings object.

Alter a setting in a object settings object.

Retrieve a setting in a global settings object.

Alter a setting in a global settings object.

Deinit wkhtmltopdf.

Must be called before any other functions.

Parameters
use_graphicsShould we use a graphics system
Returns
1 on success and 0 otherwise
See also
wkhtmltopdf_deinit

Free up resources used by wkhtmltopdf, when this has been called no other wkhtmltopdf function can be called.

Returns
1 on success and 0 otherwise
See also
wkhtmltopdf_init
Pdf global settings, wkhtmltopdf_create_global_settings, wkhtmltopdf_get_global_setting
Parameters
settingsThe settings object to change
nameThe name of the setting
valueThe new value for the setting (encoded in UTF-8)
Returns
1 if the setting was updated successfully and 0 otherwise.
See also
Setting, wkhtmltopdf_create_global_settings, wkhtmltopdf_set_global_setting
Parameters
settingsThe settings object to inspect
nameThe name of the setting to read
valueA buffer of length at least vs, where the value (encoded in UTF-8) is stored.
vsThe length of value
Returns
1 If the the setting exists and was read successfully and 0 otherwise
See also
Setting, wkhtmltopdf_create_object_settings, wkhtmltopdf_get_object_setting
Parameters
settingsThe settings object to change
nameThe name of the setting
valueThe new value for the setting (encoded in UTF-8)
Returns
1 if the setting was updated successfully and 0 otherwise.
See also
Setting, wkhtmltopdf_create_global_settings, wkhtmltopdf_set_global_setting
Parameters
settingsThe settings object to inspect
nameThe name of the setting to read
valueA buffer of length at least vs, where the value is stored (encoded in UTF-8).
vsThe length of value
Returns
1 If the the setting exists and was read successfully and 0 otherwise

This is the main method for the conversion process, during conversion progress information warning, and errors are reported using the supplied call backs. Once the conversion is done the output pdf (or ps) file will be placed at the location of the "out" setting supplied in the global settings object during construction of the converter. If this setting is not supplied or set to the empty string, the output can be retrieved using the wkhtmltopdf_get_output function.

\paragm converter The converter to perform the conversion on.

Returns
1 on success and 0 otherwise

Conversion is done in a number of named phases, this function will retrieve the number of the current conversion phase, which will be a number between 0 and wkhtmltopdf_phase_count(converter)-1.

The description (name) of any phase can be retrieved by calling the wkhtmltopdf_phase_description method.

Parameters
converterThe converter to find the current phase of
Returns
The current phase of the supplied converter
Parameters
converterThe converter to query
Returns
The total number of phases in the conversion process
See also
wkhtmltopdf_current_phase, wkhtmltopdf_phase_description

Return the largest HTTP code greater than or equal to 300 encountered during loading of any of the supplied objects, if no such error code is found 0 is returned. This function will only return a useful result after wkhtmltopdf_convert has been called.

Parameters
converterThe converter to query
Returns
The HTTP error code.

◆ CAPI() [3/6]

CAPI ( void  )

Destroy a global settings object.

add an object (web page to convert)

Set the function that should be called once the conversion has finished.

Set the function that should be called when progress have been done during conversion.

Set the function that should be called whenever conversion changes phase.

Set the function that should be called when an errors occurs during conversion.

Set the function that should be called when an warning message is issued during conversion.

Destroy a wkhtmltopdf converter object.

Normally one would not need to call this since ownership of the settings object is transfarred to the converter.

An object must be destroyed to free up its memory, once it has been destroyed it may no longer be accessed.

Parameters
settingsThe converter object to destroy
converterThe converter object on which warnings we want the callback to be called
cbThe function to call when warning message is issued
converterThe converter object on which errors we want the callback to be called
cbThe function to call when an error occurs

The number of the new phase can be found by calling wkhtmltopdf_current_phase

Parameters
converterThe converter which phase change events to call back from
cbThe function to call when phases change
See also
wkhtmltopdf_current_phase, wkhtmltopdf_phase_count, wkhtmltopdf_phase_description

The progress in percent within the current phase is given as an integer to the callback function.

Parameters
converterThe converter which progress events to call back from
cbThe function to call when progress has occurred.
See also
wkhtmltopdf_progress_description
Parameters
converterThe converter which finish events to call back from
cbThe function to call when the conversion has finished has occurred.
See also
wkhtmltopdf_convert

Add the object described by the supplied object settings to the list of objects (web pages to convert), objects are placed in the output pdf in the order of addition. Once the object has been added, the supplied settings may no longer be accessed, it Wit eventually be freed by wkhtmltopdf. If a none NULL and none empty utf8 encoded string is supplied to data, this HTML content will be converted instead of the content located at "page" setting of the supplied object settings instance.

Parameters
converterThe converter to add the object to
settingsThe setting describing the object to add
dataHTML content of the object to convert (encoded in UTF-8) or NULL

◆ CAPI() [4/6]

CAPI ( wkhtmltopdf_converter )

Create a wkhtmltopdf converter object.

The converter object is used to convert one or more objects(web sides) into a single pdf. Once a settings object has been parsed, it may no longer be accessed, and will eventually be freed. The returned converter object must be freed by calling wkhtmltopdf_destroy_converter

Parameters
settingsThe global settings to use during conversion.
Returns
A wkhtmltopdf converter object

◆ CAPI() [5/6]

Create a new global settings object for pdf conversion.

Create a new global settings object for pdf conversion, settings can be altered with wkhtmltopdf_set_global_setting, and inspected with wkhtmltopdf_get_global_setting. Once the desired settings have been set a converter object can be created using \reg wkhtmltopdf_create_converter.

Returns
A wkhtmltopdf global settings object

◆ CAPI() [6/6]

Create an object used to store object settings.

Create a new Object settings object for pdf conversion, settings can be altered with wkhtmltopdf_set_object_setting, and inspected with wkhtmltopdf_get_object_setting. Once the desired settings have been set the object can be added to a converter by calling wkhtmltopdf_add_resource.

Returns
an object settings instance

Variable Documentation

◆ cb

wkhtmltoimage_int_callback cb
Initial value:
{
reinterpret_cast<MyPdfConverter *>(converter)->error_cb = cb

◆ value

const char char * value
Initial value:
{
if (!strcmp(name, "web.printMediaType")) {
name = "load.printMediaType";
}
return reinterpret_cast<settings::PdfObject *>(settings)->set(name, QString::fromUtf8(value))

◆ vs

const char char int vs
Initial value:
{
QString res = reinterpret_cast<settings::PdfObject *>(settings)->get(name)