This module calls external programs to delegate functionality like sending E-Mail or displaying HTML. More...

Macros
#define	MAIN_ERR_PREFIX "EXT: "
	Message prefix for EXTUTILS module.

Functions
int	ext_handler_email (const char recipient, const char subject, const char *body)
	Send e-mail to single recipient. More...

int	ext_handler_uri (const char uri, int invalid)
	Start external handler for URI. More...

int	ext_editor (const char *tfpn, int async,...)
	Start external editor for article composition. More...

int	ext_editor_status (long int editor_pid)
	Poll status of external editor. More...

void	ext_editor_terminate (long int editor_pid)
	Terminate external editor. More...

const char *	ext_pp_filter (const char *article)
	External post processing filter for outgoing articles. More...

int	ext_inews (const char *article)
	Start external inews for article injection. More...

int	ext_download_file (const char lpn, const char uri)
	Download file from external source. More...

void	ext_free (void *p)
	Free an object allocated by external program delegation module. More...

Detailed Description

This module calls external programs to delegate functionality like sending E-Mail or displaying HTML.

Attention: It is required that 'PID_MAX' is not larger than 'LONG_MAX' (must be checked by build system).

Function Documentation

◆ ext_download_file()

int ext_download_file	(	const char *	lpn,
		const char *	uri
	)

Download file from external source.

Parameters

[in]	lpn	Local pathname where the file should be stored
[in]	uri	URI of file to download

Note: The caller is responsible that write permission to lpn is granted.

Returns

Zero on success (file is now stored at lpn )
-1 on unspecified error
-2 if URI scheme is not supported
-3 if authority of URI is not reachable
-4 if requested file not available via path of URI

Definition at line 1064 of file extutils.c.

References enc_ascii_check_printable(), http_download_file(), MAIN_ERR_PREFIX, and PRINT_ERROR.

◆ ext_editor()

int ext_editor	(	const char *	tfpn,
		int	async,
			...
	)

Start external editor for article composition.

Parameters

[in]	tfpn	Pathname of temporary file (with UTF-8 content) to edit
[in]	async	Flag indicating that function should return immediately

The name of the external editor is taken from the configfile. It may not be a full pathname, the editor is searched via $PATH in this case.

If async is zero, the calling thread is blocked until the process with the editor has terminated. No additional parameter should be passed.

If async is nonzero, a third parameter of type (long int*) must be passed by the caller. This function will write the PID of the editor process to this location and the editor will be started asynchronously. If this function returns success, the status of the external editor can be polled with the function ext_editor_status() using the returned PID.

Attention: The caller must ensure that the file associated with tfpn is not modifed by the caller until editing is finished (either synchronous or asynchronous).

Returns

0 if the file was successfully edited or asynchronous processing has been started successfully
Negative value on local error
Positive value if external editor reported error

Definition at line 517 of file extutils.c.

References CONF_EDITOR, config, main_debug, MAIN_ERR_PREFIX, PRINT_ERROR, conf_entry_val::s, sighandler_exec_prepare(), and conf::val.

◆ ext_editor_status()

int ext_editor_status ( long int editor_pid )

Poll status of external editor.

Parameters

[in] editor_pid PID of external editor

Attention: The value editor_pid must correspond to a value returned by ext_editor() in asynchronous mode.; It is not allowed to call this function again for the same value of editor_pid after either success or error was returned.

Returns

0 Success
-1 if external editor is still running
Other negative value on local error
Positive value if external editor reported error

Definition at line 603 of file extutils.c.

References PRINT_ERROR.

◆ ext_editor_terminate()

void ext_editor_terminate ( long int editor_pid )

Terminate external editor.

Parameters

[in] editor_pid PID of external editor

Attention: The value editor_pid must correspond to a value returned by ext_editor() in asynchronous mode.; It is not allowed to call this function multiple times for the same editor.

Definition at line 649 of file extutils.c.

◆ ext_free()

void ext_free ( void * p )

Free an object allocated by external program delegation module.

Use this function to release dynamic memory that was allocated by the external program delegation module.

Parameters

[in] p Pointer to object

Release the memory for the object pointed to by p.

Note: The pointer p is allowed to be NULL and no operation is performed in this case.

Definition at line 1143 of file extutils.c.

◆ ext_handler_email()

int ext_handler_email	(	const char *	recipient,
		const char *	subject,
		const char *	body
	)

Send e-mail to single recipient.

Parameters

[in]	recipient	Recipient (URI or RFC 5322 conformant `addr-spec` )
[in]	subject	Subject (UTF-8 NFC encoded) or `NULL`
[in]	body	Cited content for body (UTF-8 NFC encoded) or `NULL`

This function calls the external program xdg-email to handle the e-mail processing.

If recipient is an URI with mailto scheme, the parameters subject and body should be NULL and are ignored otherwise.

Attention: If subject or body contain line breaks, they must be in POSIX form (single LF). According to RFC 2368 (Section 5) this is different for an URI, therefore if an URI is passed as recipient , line breaks inside parameters must be in canonical form (CR+LF, %0D%0A with percent encoding).; The Unicode data is expected to be valid (encoding and normalization must be verified by the caller).

Note: If recipient is NULL the functions return an error. Therefore this must not be checked by the caller.

Returns

0 if e-mail program was successfully started
Negative value if start of shell failed
Positive value if shell reported an error

Definition at line 170 of file extutils.c.

◆ ext_handler_uri()

int ext_handler_uri	(	const char *	uri,
		int *	invalid
	)

Start external handler for URI.

Parameters

[in]	uri	Pointer to URI string
[out]	invalid	Pointer to invalid encoding flag

If the URI encoding of uri is invalid, a negative value is returned and a nonzero value is written to the location pointed to by invalid . Otherwise zero is written to the location pointed to by invalid .

This function calls the external program xdg-open to handle the URI.

Attention: Because the current version of xdg-open starts a WWW browser, call this function only for URIs that typically can be handled by such programs (like http:// or ftp:// types).

Note: On Apple platform, the program open is used to handle the URI.

Returns

0 if external URI handler was successfully started
Negative value if start of shell failed
Positive value if shell reported an error

Definition at line 391 of file extutils.c.

◆ ext_inews()

int ext_inews ( const char * article )

Start external inews for article injection.

Parameters

[in] article Article to inject in canonical form

Returns

Zero on success
-1 on error

Definition at line 897 of file extutils.c.

References CONF_INEWS, config, fu_check_file(), main_debug, MAIN_ERR_PREFIX, PRINT_ERROR, conf_entry_val::s, sighandler_exec_prepare(), and conf::val.

◆ ext_pp_filter()

const char* ext_pp_filter ( const char * article )

External post processing filter for outgoing articles.

Parameters

[in] article Pointer to article (in canonical form)

Note: The body of article is still in Unicode and the MIME content type is not added to the header yet.

The pathname of the external filter is taken from the configfile.

Attention: The external postprocessor is not allowed to add MIME related header fields like Content-Type and Content-Transfer-Encoding and must always create valid UTF-8 encoded data.

The Unicode normalization and conversion to the target character set is done after the postprocessing.

The caller is responsible to free the memory allocated for the result.

Returns

Pointer to postprocessed article. If the result is not equal to article , a new memory block was allocated
NULL on error

Definition at line 682 of file extutils.c.

References CONF_PPROC, config, fu_check_file(), main_debug, MAIN_ERR_PREFIX, PRINT_ERROR, conf_entry_val::s, sighandler_exec_prepare(), and conf::val.

Macros

Functions

Detailed Description

Function Documentation

◆ ext_download_file()

◆ ext_editor()

◆ ext_editor_status()

◆ ext_editor_terminate()

◆ ext_free()

◆ ext_handler_email()

◆ ext_handler_uri()

◆ ext_inews()

◆ ext_pp_filter()