OVERVIEW
========

This module is a collection of stress tests utilities, which works with the 
UPnP CyberLink for C. It has some functions to send/receive UDP and TCP
packets (multicast or unicast), some functions to load pre-formated UPnP 
messages from file (device announcements, SOAP actions, SSDP searchs, etc.),
and some text files that can be properly configured by another testing tools.


MAINTAINER
==========

Rosfran Lins Borges <rosfran.borges@indt.org.br>


FILE STRUCTURE
==============

 * msearch_msg.py, msearch_response_msg.py: creates and models some M-SEARCH 
   messages, using an already existing format, defined in a text file. These
   packets travels through a UDP protocol.
 * ssdp_notify_msg.py: creates and models some NOTIFY advertisement messages, 
   using an already existing format, defined in a text file. These
   packets travels through a UDP protocol.
 * soap_action_msg.py: creates and models some SOAP action messages, 
   using an already existing format, defined in a text file. These
   packets travels through a TCP protocol.
 * multicast_simple_client.py, multicast_simple_server.py: these source files 
   implements all the functions that sends UDP multicast packets (client),
   and listens for incoming UDP multicast messages (server). These have
   Twisted library-dependency.
 * multicast_socket_send_udp.py: implements some specific functions that sends 
   UDP multicast packets. No dependency with Python-Twisted network library.
 * notify_sender.py: sends some NOTIFY messages, can configure the packet 
   sending by: number of packets, content-length, change SSDP fields, etc.
 
DIRECTORY STRUCTURE
===================

   * stress: it contains all the Python testing scripts
   * stress/messages: stores some sample NOTIFY, SOAP, M-SEARCH messages (file extension '.msg'),
     and its related configuring parameters (the ones with file extension '.params')


THEORY OF OPERATION
===================

 * An UPnP architecture has 2 main participating entities: a Device, and a Control Point.
   The UPnP device sends a lot of advertisements (SSDP messages), which are service's 
   announcements. So, a UPnP Control Point can receive this announcements, and send
   some actions offered by the emitter (the UPnP device). There are many other possible
   transactions: a Control Point can ask for a specific Device, or any kind of service,
   and so on. There are a lot of possible scenarios, and any library implementing the 
   UPnP stack should worry about a very huge list of the requirements listed on the 
   UPnP Device Arqchitecture.
   The main goal on this simple stress test framework is to allow a non-programmer
   (i.e., a person responsible for doing software tests) to make its own test cases
   and put it running.
 

GENERATING YOUR OWN TESTS
=========================
 
 * To be able to implement a test case using this Python library, you need to follow
   the steps:
   
   1. Adds 2 text files, into the 'stress/messages' directory. The first file should 
      be named with extension '.msg'. It will contains the following message format. 
      For example: 
      
		NOTIFY * HTTP/1.1
		Server: BADANHA/201 UPnP/1.0 Product/1.1
		Cache-Control: max-age=%s
		Location: http://%s
		NTS: ssdp:alive
		NT: %s
		USN: uuid:a8e8276e-bcbd-bcba-abcd-1838ad8dc32a::%s
		HOST: %s:%s
		
	Once the function UDPSender.init_persistent(notify_type, host) is called, it will 
	return a string with all the 'printf'-like parameters (%s) filled with the 
	arguments defined in the another file you should create:
	
		[Notify SSDP Alive Params]
		maxage = 100
		host = 239.255.255.250
		nt = urn:schemas-upnp-org:device:InternetGatewayDevice:1
		location = 172.19.141.54:19/igddescs/gatedesc.xml
		port = 1900
		
	Remember to name this file with the same the first file, but with the file 
	extension '.params'.
		
   2. Create your Python source with the test case you want to implement, 
      and import the source that contains the UDP message's session (on our
      example, it is a NOTIFY message sender):
      
      from stress.notify_sender import UDPSendMsgSession
      
   3. Now, you can just call the sender function from UDPSendMsgSession, passing all
      the proper arguments, like the UDP message format/arguments to be sent, and 
      how many messages you want to multicast:

	  notify_type = 'notify_ssdp_alive_invalid_nt'
	  max_notify_number = 50
	  host = '172.19.141.54'

	  udp_send_msgs_session = UDPSendMsgSession()
	  udp_send_msgs_session.send_notify_message_from_file(notify_type, max_notify_number, host)
	  
	  This will send 50 NOTIFY messages, the message format will be loaded from the
	  'stress/messages/notify_ssdp_alive_invalid_nt.msg', and the HOST field in the 
	  'Location' header (an IP address), will be filled with the value in 'host' variable.
      

RELATIONSHIP WITH OTHER MODULES
===============================

 * There is a known dependency on the Twisted networking library, but it should be 
   used only when creating test cases using some UDP multicast server facilities.


HOW TO READ, UNDERSTAND AND INTERPRET THIS MODULE
=================================================

 * It is a must to read the UPnP Device Architecture in order to understand how Session Discovery works. 
   You can get it at the UPnP Forum web-site:
   
     * http://www.upnp.org/resources/documents/CleanUPnPDA101-20031202s.pdf
 
