pnotify.c File Reference

Implementation of the skinkit file change notification interfaces, in terms of the Microsoft Windows API. More...

#include "skinkit.h"
#include "pnotify.h"

Functions
PKNotifyDirHandle *	PKNotifyDirChangeAdd (const char *dir, PKNotifyNewFile *new_entry, void *data)
	Install a change notification handler to monitor a directory. More...
void	PKNotifyDirChangeRemove (PKNotifyDirHandle *handle, void *data)
	Remove a previously created change notification for a directory. More...
PKNotifyFileHandle *	PKNotifyFileChangeAdd (const char *dir, const char *leafname, PKNotifyFileStable *stable, void *data)
	Install a change notification handler to monitor a file. More...
void	PKNotifyFileChangeRemove (PKNotifyFileHandle *handle, void *data)
	Remove a previously created change notification for a file. More...
void	PKNotifyChangeTimeouts (uint32 *rescan_mS, uint32 *stabilise_mS)
	Set the default timeouts for scanning a hotfolder and stabilising newly-detected files in the hotfolder. More...

Detailed Description

Implementation of the skinkit file change notification interfaces, in terms of the Microsoft Windows API.

Function Documentation

PKNotifyChangeTimeouts()

void PKNotifyChangeTimeouts	(	uint32 *	rescan_mS,
		uint32 *	stabilise_mS
	)

Set the default timeouts for scanning a hotfolder and stabilising newly-detected files in the hotfolder.

The default times that the hotfolder implementation uses for polling directories and files can be changed with this call, depending on the capabilities of the platform change notification. If the platform change notification can reliably detect new files being added to a hotfolder directory and/or completion of file creation and copying operations, then the timeouts can be set high, to avoid wasting processing time whilst also supporting reduced hotfolder latency.

Parameters

rescan_mS	A pointer to the rescan time, in milliseconds. If this time is zero, the function may reset it to a preferred period between hot folder rescans.
stabilise_mS	A pointer to the file stabilisation time, in milliseconds. If this time is zero, the function may reset it to a preferred period between checks for new file stabilisation.

PKNotifyDirChangeAdd()

PKNotifyDirHandle* PKNotifyDirChangeAdd	(	const char *	dir,
		PKNotifyNewFile *	new_file,
		void *	data
	)

Install a change notification handler to monitor a directory.

Parameters

[in]	dir	The UTF-8 encoded platform directory name of the hotfolder to monitor.
[in]	new_file	A callback function to call when a new file is detected. The data pointer should be supplied to this callback function.
[in]	data	An opaque pointer that identifies the hot folder requesting the change notification, which should be passed to the callback function.

Returns

NULL if the platform does not support change notification or a change notification could not be created. Non-null if a change notification was created. If this function returns a non-NULL value, PKNotifyDirChangeRemove() will be called to remove the notification.

PKNotifyDirChangeRemove()

void PKNotifyDirChangeRemove	(	PKNotifyDirHandle *	handle,
		void *	data
	)

Remove a previously created change notification for a directory.

Parameters

handle	The change notification handle returned by PKNotifyDirChangeAdd().
data	The opaque data pointer that was passed to PKNotifyDirChangeAdd() to identify the hot folder that requested the notification.

This function should ensure that there will not be any callbacks for directory changes after it returns.

PKNotifyFileChangeAdd()

PKNotifyFileHandle* PKNotifyFileChangeAdd	(	const char *	dir,
		const char *	leafname,
		PKNotifyFileStable *	stable,
		void *	data
	)

Install a change notification handler to monitor a file.

Parameters

[in]	dir	The UTF-8 encoded platform directory name of the hotfolder in which the file resides.
[in]	leafname	The UTF-8 encoded leaf name of the newly-detected file to monitor.
[in]	stable	A callback function to call when the file is considered to be stable. The data pointer should be supplied to this callback function.
[in]	data	An opaque pointer identifying the file entry to monitor. This pointer should be passed to the callback function.

Returns

NULL if the platform does not support change notification or a change notification could not be created. Non-null if a change notification was created. If this function returns a non-NULL value, PKNotifyFileChangeRemove() will be called to remove the notification.

PKNotifyFileChangeRemove()

void PKNotifyFileChangeRemove	(	PKNotifyFileHandle *	handle,
		void *	data
	)

Remove a previously created change notification for a file.

Parameters

handle	The change notification handle returned by PKNotifyFileChangeAdd().
data	The opaque data pointer that was passed to PKNotifyFileChangeAdd() to identify the file entry that requested the notification.

This function should ensure that there will not be any callbacks for the change notification after it returns.