

GNOTIFY PROTOCOL
					
Marius M. M.
May 2004
																		
																		
																		
TABLE OF CONTENTS
						
1.	THE GNOTIFY PROTOCOL

		1.01.	APP
		1.02.	ICON
		1.03.	SND
		1.04.	BTN
		1.05.	MVX/MVY
		1.06.	MSG
		1.07.	VERSION
		1.08.	QUIT
		1.09.	GET
		1.10.	GETCFG
		
			1.10.01.	GETCFG:X
			1.10.02.	GETCFG:Y
			1.10.03.	GETCFG:DELAY
			1.10.04.	GETCFG:PLAY
			1.10.05.	GETCFG:ALLOWMOVE
			1.10.06.	GETCFG:ALLOWHTML
			1.10.07.	GETCFG:SSINK
			1.10.08.	GETCFG:ALLOWRELOAD
			1.10.09.	GETCFG:ALLOWCONFCHANGE
			1.10.10.	GETCFG:SAVECONFONEXIT
			1.10.11.	GETCFG:LOGOUT
			
		1.11.	RELOAD
		1.12.	SETCFG
		
			1.12.01.	SETCFG:X
			1.12.02.	SETCFG:Y
			1.12.03.	SETCFG:DELAY
			1.12.04.	SETCFG:PLAY
			1.12.05.	SETCFG:ALLOWMOVE
			1.12.06.	SETCFG:ALLOWHTML
			1.12.07.	SETCFG:SSINK
			1.12.08.	SETCFG:ALLOWRELOAD
			1.12.09.	GETCFG:ALLOWCONFCHANGE
			1.12.10.	GETCFG:SAVECONFONEXIT

		1.13.	LANG
		1.14.	CKB
		1.15.	SAVECONFIG
		1.16.	BTNEVENT
		
		
2.	NOTES








1.	THE GNOTIFY PROTOCOL

	The GNotify-Protocol is a very simple structured protocol used for the
	communication between a GNotify client and the GNotify daemon. It's objective
	is to provide a modern notification service with simple commands.



	1.01.	APP
		
		The APP command is used to set the notification's title. E.g. by sending
		"APP:My Application" the notification's title will be set to "My Application".
		As of GNotify 0.2 it's possible to use Pango-Tags in the title and the
		message.
		The APP command always returns a "220 Ok" to the client.


			
	1.02.	ICON
	
		The ICON command is used to set the notification's icon. The icon *must*
		exist on the box where the daemon is running. By sending
		"ICON:/usr/share/icons/myicon.png" the icon /usr/share/icons/myicon.png will
		be set, if it exists. If the command was successfull, the client will get a
		"220 Ok". If the icon couldn't be found, the client will get a "500 Icon does
		not exist". By sending "ICON:<NULL>" it's possible to remove the icon
		completely from the notification-window. It's also possible to send "ICON:".
		Then, the standard GNotify-icon will be set as icon.



	1.03.	SND
	
		SND is used to set a sound for the notification. The sound-file must
		exist on the box where the daemon is running. The syntax and the return values
		are the same like the ICON's one.
			Note: It's possible to get an 220 but the sound will not be played, because
		of the user's configuration.



	1.04.	BTN
	
		BTN sets up a button on the notification-window. By sending "BTN:Click me"
		you can set up a button labeled with "Click me". By sending "BTN:<NULL>" an
		existing button will be removed. The standard return value of the BTN-command
		is "220 Ok". If the client sets up a button and the user presses it before the
		notification gots his timeout, then the notification will be closed and the
		client will get a "221 Button pressed". If CKB and BTN are pressed then
		the client will get a "223 Checkbox and Button pressed".



	1.05.	MVX/MVY
	
		The commands MVX and MVY provide a moving-function for the notification
		window. By sending as example "MVX:0" and "MVY:0" the notification window will
		be moved to the top left corner of the screen. If the moving was successfull
		the client gets a "220 Ok", else a "500 Moving is not allowed" (if the user's 
		configuration do not allow applications to move the notification window).
			Note: This is a feature which exists since GNotify 0.7. Older version will
		return a "510 Unrecognized command".


	
	1.06.	MSG
	
		This command sets a notification message and shows the notification. The
		client always will get a "220 Ok", even if something goes wrong (like the
		forking/threading or else).
			Note: If the client waits for the return value of MSG and the user didn't
		enable the gtk-forking/-threading, the client will idle till the gtk-function
		gets it's timeout and quits. The default timeout is 5000ms.



	1.07.	VERSION
	
		The VERSION command is used to get the version of the currently running
		GNotify-daemon. This command returns "214 %version%".
			Note: You *should* check the version till you're sending commands like MVX
		or MVY!



	1.08.	QUIT
	
		This command is used to terminate a GNotify-session. This command doesn't
		return anything.



	1.09.	GET
	
		The GET command is a new feature (available since GNotify 0.8) to provide a
		little html information-page for http browsers. Just surf to
		http://<gnotify-host>:7206/ with your browser.



	1.10. GETCFG
	
		This command is used by clients to get some config-information of GNotify.
		GETCFG needs an argument (see 1.10.x) and returns everytime on success
		"214 <argument>:<value>" or "510 Unrecognized argument for GETCFG:" on
		error.
		
		
		
		1.10.01	GETCFG:X
		
			Get the default X-Position of the notification-window.
		
		
		
		1.10.02	GETCFG:Y
		
			Get the default Y-Position of the notification-window.
		
		
		
		1.10.03	GETCFG:DELAY
		
			Get the default delay (in ms) till the notification terminates.
		
		
		
		1.10.04	GETCFG:PLAY
		
			Returns 0 or 1 and indicates whether GNotify plays sounds or not.
		
		
		
		1.10.05	GETCFG:ALLOWMOVE
		
			Returns 0 or 1 and indicates whether GNotify allows the client to move the
			notification-window or not.
		
		
		
		1.10.06	GETCFG:ALLOWHTML
		
			Returns 0 or 1 and indicates whether GNotify allows the command GET which is
			used by http-browsers or not.
		
		
		
		1.10.07	GETCFG:SSINK
		
			Returns the Sound-Sink which is used for playing sounds.			
		
		
		
		1.10.08	GETCFG:ALLOWRELOAD
		
			Returns 0 or 1 and indicates whether GNotify allows the command RELOAD which
			allows a client to reload the config-file.
		
		
		
		1.10.09	GETCFG:ALLOWCONFCHANGE
		
			Returns 0 or 1 and indicates whether GNotify allows clients to change things
			in the configuration-file.
		
		
		
		1.10.10	GETCFG:SAVECONFONEXIT
		
			Returns 0 or 1 and indicates whether GNotify shall save the current
			configuration into the configuration-file on exit.

	
	
		1.10.11	GETCFG:LOGOUT
		
			Returns the log output.

	
	
	1.11.	RELOAD
	
		This command is used by clients to reload the configuration-file of GNotify.
		On success it returns "220 Ok", else "500 RELOAD is not allowed".



	1.12. SETCFG
	
		This command is used by clients to set some config-information of GNotify.
		SETCFG needs two arguments (see 1.12.x) and returns everytime on success
		"220 Ok" or "510 Unrecognized argument for SETCFG:" on
		error. A SETCFG command should look like this: SETCFG:<argument>:<value>
		Note: This command only works if the GNotify configuration allows it by
		<allowcfgchange>1</allowcfgchange>! If it is not allowed you'll get a 
		"500 Configuration changes not allowed".
		
		
		
		1.12.01	SETCFG:X
		
			Set the default X-Position of the notification-window.
		
		
		
		1.12.02	SETCFG:Y
		
			Set the default Y-Position of the notification-window.
		
		
		
		1.12.03	SETCFG:DELAY
		
			Set the default delay (in ms) till the notification terminates.
		
		
		
		1.12.04	SETCFG:PLAY
		
			Set 0 or 1 to indicate whether GNotify plays sounds or not.
		
		
		
		1.12.05	SETCFG:ALLOWMOVE
		
			Set 0 or 1 to indicate whether GNotify shall allow the client to move the
			notification-window or not.
		
		
		
		1.12.06	SETCFG:ALLOWHTML
		
			Set 0 or 1 to indicate whether GNotify shall allow the command GET which is
			used by http-browsers or not.
		
		
		
		1.12.07	SETCFG:SSINK
		
			Set the Sound-Sink which is used for playing sounds.			
		
		
		
		1.12.08	SETCFG:ALLOWRELOAD
		
			Set 0 or 1 to indicate whether GNotify shall allow the command RELOAD which
			allows a client to reload the config-file.
		
		
		
		1.12.09	SETCFG:ALLOWCONFCHANGE
		
			Set 0 or 1 to indicate whether GNotify shall allow clients to change things
			in the configuration-file.
		
		
		
		1.12.10	SETCFG:SAVECONFONEXIT
		
			Set 0 or 1 to indicate whether GNotify shall save the current
			configuration into the configuration-file on exit.



	1.13.	LANG
	
		This command is used by clients to get the language which is used on the
		GNotify daemon computer/server. This command returns "214 LANG:<language>" on
		success.



	1.14.	CKB
	
		CKB sets up a checkbox on the notification-window. By sending "CKB:Check me"
		you can set up a checkbox labeled with "Check me". By sending "CKB:<NULL>" an
		existing checkbox will be removed. The standard return value of the
		CKB-command is "220 Ok". If the client sets up a button and the user presses
		it client will get a "222 Checkbox pressed" after the notification timed out.
		If CKB and BTN are pressed then	the client will get a "223 Checkbox and
		Button pressed".



	1.15.	SAVECONFIG
	
		SAVECONFIG provides on-the-fly saving of the current configuration of
		GNotify. This is only possible if the configuration-file allows it by
		<allowcfgchange>1</allowcfgchange>. If saving was successfull, GNotify returns
		"220 Ok". If this command is not allowed, GNotify returns "500 SAVECONFIG is
		not allowed".



	1.16.	BTNEVENT
	
		BTNEVENT sets up a button-event for the notification-button. This is needed
		if you need to do things like opening URLs or files on-buttonclick while
		you're running the GNotify-clients on another machine than the daemon.
		A BTNEVENT command could look like this:
		BTNEVENT:HTTP:http://www.google.com
		Available protocols are: HTTP, FTP and FILE. The command will return
		"220 Ok" on success or "510 Unrecognized Button-Event type: <>" on error
		(e.g. if you want to set a protocol which is not available).



2.	NOTES

	Hints for client developers:
	At first, every string you send to the daemon must be nul-terminated. 
	Non-null-terminating strings will be interpreted wrong. Also you should 
	check every return value the daemon sends back. It might happen, that the
	daemon sends back a "0 QUIT" and closes the connection. If so, your client
	would send strings into the nirvana, so please check every return value!
	And please don't just disconnect from the server without sending the QUIT
	string. It's impolite to go without saying "Goodbye" ;)

-- EOF ---
