A RenderWare stream is defined as a platform independent, sequential access device. Three types of stream are currently supported by RenderWare. The stream type required is specified when calling RwOpenStream() as follows:
• rwSTREAMFILE A stream file is a standard file stream which has been opened by the user. The device dependent parameter should be of FILE * type and should be a valid file handle.
• rwSTREAMFILENAME Opens a file using the given filename. The device dependent parameter should be of char * type and this should point to the required filename.
• rwSTREAMMEMORY Performs operations to/from a chunk of memory. The device dependent parameter should be a RwMemory * structure for rwSTREAMREAD opens. The RwMemory structure should be filled in with the details of the memory section where reading should occur from.
When opening a stream the type of access is also specified this can be one of
• rwSTREAMREAD The stream can only be read from.
• rwSTREAMWRITE The stream can only be written to.
• rwSTREAMAPPEND The stream can only be appended to.
For example to open a write memory stream the following could be used
RwStream *stream;
stream = RwOpenStream(rwSTREAMMEMORY, rwSTREAMWRITE, NULL);
Once a stream has been opened it can be written to if it is an rwSTREAMWRITE or a rwSTREAMAPPEND stream. This performed with the RwWriteStream() function.
char string[]="hello world";
if
(!RwWriteStream(stream, string, sizeof(string)))
{
printf("An error has occurred writing to the
stream\n");
return FALSE;
}
Reading from a stream is performed similarly with the RwReadStream() function.
char buffer[20];
if
(!RwReadStream(stream,buffer,20)))
{
printf("An error has occurred reading from the
stream\n");
return FALSE;
}
Once reading or writing has finished on a stream it is necessary to close the stream this is performed with the function RwCloseStream() . This function is passed two parameters, one the stream to be closed and the other a stream type dependent parameter.
Currently only the rwSTREAMMEMORY type requires this extra parameter and should be set to point to an RwMemory structure which will be filled in. Other types should pass this parameter as NULL.
Note that when an rwSTREAMMEMORY is used and data is written, RenderWare uses the standard malloc and realloc to allocate the chunks of memory. When the stream is closed the RwMemory structure is filled in with the pointer to the malloced chunk of memory in the 'start' field and the length of the data held in the chunk of memory in 'length'. Once finished with this chunk of memory it is advisable to free it with free.
The following example opens writes some data to and closes a memory file stream. Then it reads the written chunk back and compares it with what was originally written.
RwStream
*stream;
RwMemory memory;
char
message[]="Memory stream\n";
char buffer[80];
/* Open the memory stream */
stream = RwOpenStream(rwSTREAMMEMORY, rwSTREAMWRITE, NULL);
if (!stream)
{
/* Unable to open memory stream */
printf("Error opening the stream\n");
return FALSE;
}
/* write to the memory stream */
if
(!RwWriteStream(stream, message, sizeof(message)))
{
/* Unable to write to stream */
printf("Error writing the stream\n");
return FALSE;
}
/* Close the stream */
if
(!RwCloseStream(stream, &memory))
{
/* Error when closing the stream */
printf("Error closing the write stream\n");
return FALSE;
}
/* Read back in the saved stream */
stream = RwOpenStream(rwSTREAMMEMORY, rwSTREAMREAD, &memory);
if (!stream)
{
/* Unable to open stream for read */
printf("Error opening stream for read the
stream\n");
return FALSE;
}
{
char letter;
RwInt32 i=0;
while
(RwReadStream(stream, &letter, sizeof(letter)))
{
buffer[i] = letter;
i++;
}
}
/* Close the stream */
if (!RwCloseStream(stream, NULL))
{
/* Error closing stream */
printf("Error closing the read stream \n");
return FALSE;
}
/* Free the memory allocated by the write */
free(memory.start);
/* Check what was read was what was written */
if
(strcmp(buffer, message))
{
printf("Error reading or writing the
stream\n");
return FALSE;
}
return TRUE;