[libfaim.git] / utils / aimdebugd / README


aimdebugd.  Slightly ambiguous name.  Basically, its a
micro-aim-server thats meant to be hacked.  Its completely useless the
way it is, but it does let you poke and prod at clients while they're
in their main loop.  It won't help for debugging the login process,
but it will allow you to test various ICBM types, etc -- anything you
want to implement packet handlers and transmitters for.  

How to make your client work with aimdebugd
-------------------------------------------
	1. Create a handler for the debug connection SNAC like this:

int debugconn_connect_handler(struct aim_session_t *sess, struct command_rx_struct *command, ...) {

	printf("connecting to an aimdebugd!\n");

	/* convert the authorizer connection to a BOS connection */
	command->conn->type = AIM_CONN_TYPE_BOS;

	/* You may want to add some of your BOS callbacks here */

	/* tell the aimdebugd we're ready */
	aim_debugconn_sendconnect(sess, command->conn); 

	/* go right into main loop (don't open a BOS connection, etc) */
	return 1;
}

	2. Connect the handler to your authorizer connection before 
		calling aim_send_login() or aim_select():

	...
	aim_conn_addhandler(sess, authconn, AIM_CB_FAM_SPECIAL,
				AIM_CB_SPECIAL_DEBUGCONN_CONNECT, 
				debugconn_connect_handler, 0);
	...

	3. Start your client with the authorizer host set to the box
		running the aimddebugd.


Writing Halfscripts
-------------------

Some hacking of aimdebugd can be done without writing any C.  But it
its write-only.  

Once aimdebugd gets the acknowledgment from the client, it can begin
to run through a file (passed through a command line) that contains a
listing of excruciatingly simple "commands" and react to it.  The
commandset is very small, and, as mentioned above, is write-only --
its not event driven.  The list of commands is executed linearly and
does not stop until it hits the break command, hits the end of the
file, hits the disconnect command, or the connection to the client
dies.

Commands:
	# -- Comment
	b -- Breaks execution, leaves connection open
	d -- Disconnects from client (results in connection termination)
	e <msg> -- Prints msg to stderr
	m <srcsn>/<msg> -- Sends msg from srcsn to the client
	s <seconds> -- Sleeps for an arbitrary number of seconds
	
Note that the client must have callbacks connected to the appropriate
handlers if it wants to react to any of the output from these commands
(except 'e', thats just there).
Commit	Line	Data
e5012450	1
	2	aimdebugd. Slightly ambiguous name. Basically, its a
	3	micro-aim-server thats meant to be hacked. Its completely useless the
	4	way it is, but it does let you poke and prod at clients while they're
	5	in their main loop. It won't help for debugging the login process,
	6	but it will allow you to test various ICBM types, etc -- anything you
	7	want to implement packet handlers and transmitters for.
	8
	9	How to make your client work with aimdebugd
	10	-------------------------------------------
	11	1. Create a handler for the debug connection SNAC like this:
	12
	13	int debugconn_connect_handler(struct aim_session_t sess, struct command_rx_struct command, ...) {
	14
	15	printf("connecting to an aimdebugd!\n");
	16
	17	/* convert the authorizer connection to a BOS connection */
	18	command->conn->type = AIM_CONN_TYPE_BOS;
	19
	20	/* You may want to add some of your BOS callbacks here */
	21
	22	/* tell the aimdebugd we're ready */
	23	aim_debugconn_sendconnect(sess, command->conn);
	24
	25	/* go right into main loop (don't open a BOS connection, etc) */
	26	return 1;
	27	}
	28
	29	2. Connect the handler to your authorizer connection before
	30	calling aim_send_login() or aim_select():
	31
	32	...
	33	aim_conn_addhandler(sess, authconn, AIM_CB_FAM_SPECIAL,
	34	AIM_CB_SPECIAL_DEBUGCONN_CONNECT,
	35	debugconn_connect_handler, 0);
	36	...
	37
	38	3. Start your client with the authorizer host set to the box
	39	running the aimddebugd.
	40
	41
	42	Writing Halfscripts
	43	-------------------
	44
	45	Some hacking of aimdebugd can be done without writing any C. But it
	46	its write-only.
	47
	48	Once aimdebugd gets the acknowledgment from the client, it can begin
	49	to run through a file (passed through a command line) that contains a
	50	listing of excruciatingly simple "commands" and react to it. The
	51	commandset is very small, and, as mentioned above, is write-only --
	52	its not event driven. The list of commands is executed linearly and
	53	does not stop until it hits the break command, hits the end of the
	54	file, hits the disconnect command, or the connection to the client
	55	dies.
	56
	57	Commands:
	58	# -- Comment
	59	b -- Breaks execution, leaves connection open
	60	d -- Disconnects from client (results in connection termination)
	61	e <msg> -- Prints msg to stderr
	62	m <srcsn>/<msg> -- Sends msg from srcsn to the client
	63	s <seconds> -- Sleeps for an arbitrary number of seconds
	64
65	Note that the client must have callbacks connected to the appropriate
66	handlers if it wants to react to any of the output from these commands
67	(except 'e', thats just there).
68
69
70