==========================
Reading HOOPS stream files
==========================

The function supplied by the base classes to perform black-box reading of a HOOPS Stream File is ``TK_Read_Stream_File``.

Black-box reading using ``TK_Read_Stream_File`` requires the following steps:

#. Create a ``BStreamFileToolkit`` object
#. Register custom opcode handlers registered with the ``BStreamFileToolkit`` object
#. Pass the ``BStreamFileToolkit`` object into ``TK_Read_Stream_File`` 

It is only necessary to register opcode handlers to deal with the HSF opcodes objects that are of interest (and will be mapped to custom data structures). Opcodes in the file which do not have a custom opcode handler registered for them will be handled by the ``BStreamFileToolkit`` object`'s 'default' opcode handler; this default handler will simply skip over the opcode. The toolkit can notify you of HSF file objects which do not have a custom opcode-handler registered for them, if you set the #TK_Flag_Unhandled_Opcodes bit in the *flags* parameter of the reading function. (It will return ``#TK_Error`` for unhandled opcodes) 

Let's take the case where the reading application only cares about reading the segment and shell objects from HSF files. This could be supported via the following code:

.. code-block:: cpp

	#include "BStream.h"  

	void my_reading_function()  
	{  
		TK_Status  status;
		  
		BStreamFileToolkit * tk = new BStreamFileToolkit;  

		tk->SetOpcodeHandler (TKE_Open_Segment, new TK_My_Open_Segment); 
		tk->SetOpcodeHandler (TKE_Close_Segment, new TK_My_Close_Segment);    
		tk->SetOpcodeHandler (TKE_Shell, new TK_My_Shell);  

		status = TK_Read_Stream_File("sample.hsf", tk);  

		if (status == TK_Version)  
		{ 
			MessageBox("This file was created    with a newer version of the 
						HOOPS/Stream Toolkit.\nTo view it this application's 
						version of the toolkit will need to be updated."); 
		} else if (status = TK_Error) 
			MessageBox("Error reading file.");    
	} 
