Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!seismo!rutgers!ames!ucbcad!ucbvax!CORY.BERKELEY.EDU!dillon
From: dillon@CORY.BERKELEY.EDU (Matt Dillon)
Newsgroups: comp.sys.amiga
Subject: Proposal for resource standard
Message-ID: <8705020427.AA23076@cory.Berkeley.EDU>
Date: Sat, 2-May-87 00:27:01 EDT
Article-I.D.: cory.8705020427.AA23076
Posted: Sat May  2 00:27:01 1987
Date-Received: Sun, 3-May-87 04:31:19 EDT
Sender: daemon@ucbvax.BERKELEY.EDU
Lines: 138


	RFAC (Request For Amiga Comments!)

PROPOSAL FOR EMBEDDED RESOURCE STANDARD (RESOURCE LIST EMBEDDED IN 
EXECUTABLE):

	If we could decide on a standard for embedding resources in an 
	executable, one could get as much functionality in 'changing' 
	amiga resources as the MAC does. 

	(A) Make as little work as possible for the programmers so they 
	actually use it.  Needless to say, it would be completely optional,
	and the programmer can include any structure he wishes (and not
	include structures he doesn't want to change).

	(B) Make the standard diverse enough to handle *anything*.  My
	proposal below will be able to do that.... no worry about future
	compatibility!

---------- My Proposal -----------

	We already have a standard..... Whenever one specifies a font, you use
	a TextFont structure.  Whenever you build a menu, you use a Menu
	structure, etc.... there are literally hundreds of structures that
	we programmers use every day.  Many of our programs statically define
	these structures.

	There are already some programs out there that search around for
	structures in an executable and modify them.

	But that's dangerous... such a program could easily come across a part
	of some executable which *looks* like, say a NewWindow structure and 
	really isn't.

	So what we need is this:

		-Know where in the executable to look for our 'resource list'
		-A way of identifying and locating each resource.


	(A) WHERE TO LOOK:

	-Have ONE well known 'magic cookie' which heads the resource structure
	in the initialized data section.   There is still a possibility of
	an accidental match, so we need two more conventions:
		(A) If The resource list / modification program finds more 
		than one magic cookie, it uses the last one it finds.

		(B) The programmer places his resource list as far to the
		end of his initialized data segment as possible... e.g. in
		the last link file if possible. (but not a requirement!)
	
	-The resource structure itself is designed such that it is not
	possible to come accross an accidental magic cookie inside itself.
	In this way, you are GUARENTEED to get the correct resource 
	structure assuming the executable contains one.

	(B) HOW TO IDENTIFY STATIC STRUCTURES ELSEWHERE IN THE PROGRAM:

		-The resource structure would contain pointers to the resources
		themselves, which can be anywhere in the executable.

		-The resource structure identifies the structures by their
		structure name (as you find in a struct definition)
		Result: A intelligent resource list / modification utility 
		could extract structure definitions from #include files and
		automatically be able to handle any resource... you wouldn't
		have to hardwire everything.

------------------------
RESOURCE STRUCTURE ITSELF:

	Hopefully the resource structure version will never change, but we put
	it in just in case.    This is a static structure definition.


	The Potential of the resource modification/list utilitiy is that
	it would be able to handle ANY structure given it.... even to the
	point of the programmer defining his own structures (All you need
	is his structure definition).


	struct EXResourceHeader {
		UBYTE magiccookie[8]	/* HEX: 84 41 23 0D A5 3C 8C 65	*/
		long version;		/* resource structure version   */
		struct EXResource *ptr;	/* Pointer to array of EXResource's*/
		char *comment;		/* optional comment (else NULL)	*/
	};

	struct EXResource {
		char *structure;	/* ascii structure NAME		*/
		char *comment;		/* optional comment (else NULL)	*/
		APTR pointer;		/* pointer to structures in question */
	} array[];			/* any number of entries	*/

	The last entry in the EXResource array would have the 'structure'
	element equal to NULL.  Thus, we don't need a 'number of entries'
	entry (which is tedious for a programmer to have to update).

	the 'pointer' is a static pointer to the resource itself, which can
	be somewhere else in your program.  EXAMPLE:

	******************************************************
	(Somewhere in your program)
	struct TextFont Ta = { "topaz.font", 8 };
	struct NewWindow Nw = {  ... blah ... };


	(Resource Definition)

	struct EXResource Dummy1[] = {
		"TextFont", "The default textfont", &Ta,
		"NewWindow", NULL, &Nw,
		NULL, NULL, NULL
	};

	struct EXResourceBase  Dummy2[] = {
		{ 0x84, 0x41, 0x23, 0x0D, 0xA5, 0x3C, 0x8C, 0x65 },
		1,
		&Dummy1,
		"MY AweSome Program"
	};
	******************************************************

	The Resource List / Modification Program:

	If you don't want to deal with the Executable's  OFFSET hunks (which
	will probably occur since you have pointer references), you can 
	simply do a LoadSeg() of the code to find the 'actual' pointer
	offsets relative to whatever Hunk that pointer is pointing into...

	In the case of modification, you then simply modify the CODE or DATA
	hunks in the executable on disk using the offset you determined from
	the resolved pointers in the LoadSeg() (The offset is calculated by
	taking  pointer - hunkbase  for the particular hunk that pointer is
	pointing to).

						-Matt