Network Metamorph API Data Types

This API was generated with Thunderstone's NCG program (Network Code Generator), and uses several of the data types that are specially defined within that application. For more information on NCG's data types please see its manual pages. For the most part you will not need to understand NCG in order to use these data types, just their usage as it pertains to the API. The following data types are the NCG fundamental types used within the API:

xxxxxxxxxxxx = 
int      >  Just a normal 'C' integer                                  
str      >  A char * to a string that is terminated with a '\0'         
str  *   >  An array of str's with the last one pointing to a '\0'      
void *   >  The abstracted ANSI data pointer                            
char *   >  A char * with no other meaning inferred                     
buffer   >  A compound data type for used for block data transfers      
long     >  Just a normal long value ( but don't trust it past 32 bits )
func     >  A function pointer

The reason that the special types are defined is so that the NCG protocol generator can obtain information about how much data it will need to transfer between the client and server programs. It is in this way that we can lower the number of special function calls needed to move data back and forth.

Mostly you will be dealing with the str and str * data types within the Metamorph API. You are probably very familiar with the str because this type is the the same as the ASCIIZ type that is passed to the functions in "string.h" like strcmp() for example. Strings passed as this type must be '\0' terminated, but can be of any reasonable length. All bytes after the '\0' byte are ignored and will not be moved between the client and server.

The str * type is nothing more than array (or list) of str types. Since Metamorph relies pretty heavily on lists of strings, we thought we ought to make their manipulation a little easier. A str * is taken to mean a list of str types with the last entry in the list pointing directly to a '\0'. So, the following declaration could legally be cast into a str *:

char *mylist[]=
{
 "doe a deer",
 "ray a drop",
 "me a name" ,
 "fa a long" ,
 ""            /* <--- please take note of the terminator */
};

The func data type is a synonym for int (*)() or in english; " A pointer to a function that returns an integer result." We use this data type any time a server function has the need to call a client function and optionally pass it some data.

The other type that you may have noticed but not recognized in the list is the buffer type. But not to worry, you probably won't have to directly interact with it because we've buried its usage within the api to protect the innocent. The buffer type is used whenever we need to pass some arbitrary block of data between the client and server (like in the n_rread() and n_rwrite() functions). If you are really curious about how it works, see the NCG section.