-----------------------
Summary
--------------------------

PostgreSQLDatabase implements the listen and notify protocol of PostgreSQL databases with the following API:

PostgreSQLDatabase Methods:

Listen(name as String): listen for notifications named 'name'.

Unlisten(name as String): stop listening for notifications named 'name'.

Notify(name as String): send a notification named 'name'.

CheckForNotifications: check to see if there are any waiting notifications. At most, only one notification will be received for any call of CheckNotifications, so you will need to call CheckNotifications periodically to continue to receive them. One strategy would be to put the call to CheckForNotifications in a Timer's Action event.


PostgreSQLDatabase Events:

ReceivedNotification(name as String, pid as Integer, extra as String): a notification named 'name' has been received. The pid of the sender is 'pid'. According to the PostgreSQL documentation, the 'extra' argument will always be empty, although it may be implemented in the future.



-----------------------
Details
--------------------------

To send a notification, call the PostgreSQLDatabase.Notify method with the name of the notification you want to send. For example, if you wanted to send a notification called "test notification", you would call notify like this:

dim db as new PostgreSQLDatabase
<connection code here>
db.Notify "test notification"


To check for notifications, call the PostgreSQLDatabase.CheckForNotifications method. You will receive notifications as a PostgreSQLDatabase.ReceivedNotification event. The ReceivedNotification event is called with three arguments: the name of the notification as a String (this is the same name that you send with the Notify method, as explained above), the pid of the process sending the notification as an Integer, and an extra argument that the PostgreSQL documentation says is not used at this time.

If you would like to check for notifications automatically, at some set interval, then use a Timer and call CheckForNotifications in the Timer's Action event.

In order to implement the ReceivedNotification event, you will need to either instantiate a PostgreSQLDatabase object on a Window, or you will need to subclass PostgreSQLDatabase.

Accompanying this ReadMe are two applications, Notify and Listen, that demonstrate how to send notifications and how to listen for them. Listen implements ReceivedNotification by instantiating a PostgreSQLDatabase object on Window1.