|
www.riscos.com Technical Support: |
Various names and numbers that appear in RISC OS must be registered with Acorn to ensure that they don't clash with those used by other programmers. This appendix tells you what those names and numbers are, and how to register them with Acorn.
Generally, you can propose the name(s) that you would like to use, and will be allocated them if they are previously unused. However, numbers are normally allocated consecutively, so you are unlikely to have any choice as to which ones you are allocated.
Acorn keeps a single central set of header files that record all such names and numbers. Your request will be checked against the relevant file. Finally, your allocation will be recorded in the file, and you will be informed of it.
If you need to use a new filetype, you must register it with Acorn.
You should give a proposed textual equivalent for the filetype (8 characters maximum, as used by the 'Full info' Filer displays), and a more complete description of the filetype's functionality and/or conformance to any standards. Acorn will then inform you whether your name is unique, and - if it is unique - which filetype number you have been allocated.
For a list of currently defined filetypes, see Table C: File types.
Registering filetypes is necessary to prevent any clashes in the Wimp's sprite pool between different 'file_XXX' and 'small_XXX' sprites (where XXX is a hexadecimal filetype) used by the Filer to display the filetype. Once you have registered a filetype, you may consider such sprites as also registered.
Registering filetypes is also necessary to prevent any clashes between File$Type_XXX, Alias$@LoadType_XXX, Alias$@PrintType_XXX and Alias$@RunType_XXX system variables (where XXX is a hexadecimal filetype). Once you have registered a filetype, you may consider such variables as also registered.
If you need to supply your own SWIs, you must ask Acorn for an allocation of a SWI chunk number, the use of the SWIs within which you can then determine yourself.
You should give a proposed name for the SWI chunk. Acorn will then inform you whether your name is unique, and - if it is unique - which SWI chunk number you have been allocated.
SWIs are named as ChunkName_FunctionName (so in Wimp_Initialise, Wimp is the chunk name, and Initialise is the function name). The chunk name is normally the name of the application or module providing the SWI, which will itself need registration - see below.
For more information on SWI numbers and names, see the chapter entitled An introduction to SWIs.
Wimp message numbers are allocated by Acorn from the same number space as SWI numbers. If you need to use a new Wimp message and have a SWI chunk allocated, you may use as Wimp message numbers the same 64 numbers that are held in that SWI chunk. Otherwise you must ask Acorn for an allocation of a range of Wimp message numbers, the use of which you can then determine yourself.
For more information on Wimp messages, see Wimp_SendMessage.
If you need to generate your own errors, you must ask Acorn for an allocation of a range of error numbers, the use of which you can then determine yourself.
For more information on error numbers, see the chapter entitled Error numbers.
If you create your own filing system, you must register it with Acorn.
You should give a proposed name for the filing system, and a more complete description of its functionality and/or conformance to any standards. Acorn will then inform you whether your name is unique, and - if it is unique - which filing system number you have been allocated.
For a list of currently defined filing system numbers, see the chapter entitled Filing system information word.
If you create an expansion card, you must ask Acorn for an allocation of a manufacturer code and a product type code.
You should give a brief description of its functionality and/or conformance to any standards. Acorn will then inform you which codes you have been allocated.
For more information on these codes, see the chapter entitled Extended Expansion Card Identity.
There are 4 bytes of CMOS RAM reserved for each expansion card slot, which your expansion cards may freely use; see the chapter entitled Non-volatile memory (CMOS RAM). For all other purposes you should remember state in some other manner (for example using an App$Options system variable in a desktop boot file, or using a Choices file within your application). It is only in very exceptional circumstances that Acorn may allocate CMOS RAM bytes to other parties.
If you need to use a new territory, country, or alphabet, you must register it with Acorn.
You should give a proposed name for the territory, country, or alphabet, and (for alphabets) a more complete description of its functionality and/or conformance to any standards. Acorn will then inform you whether your name is unique, and - if it is unique - which territory, country, or alphabet number you have been allocated.
For a list of currently defined country and alphabet numbers, see the chapter entitled Names and numbers.
If you need to use a new object type or tagged object type in a Draw file, you must register it with Acorn.
For an object type you should give full details of its file format. For a tagged object type you should give a brief description of the purpose of the tag. Acorn will then inform you which type numbers you have been allocated.
For a list of currently defined object types and tagged object types, see the chapter entitled Draw files.
If you create a new module, you must register it with Acorn, since only one module of a given name can be loaded at once.
You should give a proposed name for the module and a brief description of its functionality. Acorn will then inform you whether your name is unique, and hence if you may use it.
Registering module names is also necessary to prevent any clashes between system variables used by modules, such as Module$Options. Once you have registered the module name 'Module', you may consider all variables beginning with 'Module$' as also registered.
To ensure there are no clashes with 'App$' or 'Resource$' system variables, Acorn will also check that your module name does not match any other programmers' registered application or shared resource names. However, you may register identical module, application and /or shared resource names; it is then your responsibility to prevent any clashes between your own system variables.
If you create a new application, you must register it with Acorn.
You should give a proposed name for the application and a brief description of its functionality. Acorn will then inform you whether your name is unique, and hence if you may use it.
Registering application names is necessary to prevent any clashes in the Wimp's sprite pool between different application's '!app' and 'sm!app' sprites, used by the Filer to display the application directory's icon. Once you have registered an application name, you may consider such sprites as also registered.
Registering application names is also necessary to prevent any clashes between system variables used by applications, such as App$Dir or App$Options. Once you have registered the application name 'App', you may consider all variables beginning with 'App$' as also registered.
To ensure there are no clashes with 'Module$' or 'Resource$' system variables, Acorn will also check that your application name does not match any other programmers' registered module or shared resource names. However, you may register identical module, application and /or shared resource names; it is then your responsibility to prevent any clashes between your own system variables.
If you create a new shared resource directory, you must register it with Acorn.
You should give a proposed name for the shared resource and a brief description of its functionality. Acorn will then inform you whether your name is unique, and hence if you may use it.
Registering shared resource names is necessary to prevent any clashes in the Wimp's sprite pool between different shared resource's '!resource' and 'sm!resource' sprites (used by the Filer to display the shared resource directory's icon). Once you have registered an shared resource name, you may consider such sprites as also registered.
Registering shared resource names is also necessary to prevent any clashes between system variables used by shared resources, such as Resource$Dir. Once you have registered the shared resource name 'Resource', you may consider all variables beginning with 'Resource$' as also registered.
To ensure there are no clashes with 'Module$' or 'App$' system variables, Acorn will also check that your shared resource name does not match any other programmers' registered module or application names. However, you may register identical module, application and /or shared resource names; it is then your responsibility to prevent any clashes between your own system variables.
If you create a new * Command, you must register it with Acorn.
You should give a proposed name for the command, and a brief description of its functionality. Acorn will then inform you whether your name is unique, and hence if you may use it.
If you add a sprite to the Wimp sprite pool - for example using *IconSprites - you must register it with Acorn.
You should give a proposed name for the sprite. Acorn will then inform you whether your name is unique, and hence if you may use it.
Provided you have registered a filetype, application or shared resource, you need not register the associated sprites that the Filer uses to display them. See Associated sprites, Associated sprites and Associated sprites respectively.
You should not register the names of sprites that are held in your applications' own sprite areas. Desktop applications must not use the system sprite pool.
If you create a new font, you must register it with Acorn.
You should give a proposed name for the font. Acorn will then inform you whether your name is unique, and hence if you may use it.
If you need to add a new device, you must ask Acorn for an allocation of a major and a minor device number.
You should give a brief description of the device's functionality. Acorn will then inform you which device numbers you have been allocated.
If you create a new printer driver or dumper module, you must ask Acorn for an allocation of a printer driver or dumper number.
You should give a brief description of the printer driver or dumper's functionality. Acorn will then inform you which ID number you have been allocated.