Amiga Developer CD 1.2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 1.2 / amidev_cd_12.iso / contrib / iam / networking / envoy-2.0 / doc / nipc.doc < prev next >

Wrap

Text File | 1994-12-22 | 49.6 KB | 1,545 lines

TABLE OF CONTENTS nipc.library/AbortTransaction nipc.library/AddRoute nipc.library/AllocNIPCBuff nipc.library/AllocNIPCBuffEntry nipc.library/AllocTransactionA nipc.library/AppendNIPCBuff nipc.library/BeginTransaction nipc.library/CheckTransaction nipc.library/CopyFromNIPCBuff nipc.library/CopyNIPCBuff nipc.library/CopyToNIPCBuff nipc.library/CreateEntityA nipc.library/DeleteEntity nipc.library/DeleteRoute nipc.library/DoTransaction nipc.library/FindEntity nipc.library/FreeNIPCBuff nipc.library/FreeNIPCBuffEntry nipc.library/FreeTransaction nipc.library/GetEntityAttrsA nipc.library/GetEntityName nipc.library/GetHostName nipc.library/GetTransaction nipc.library/LoseEntity nipc.library/NIPCBuffLength nipc.library/NIPCBuffPointer nipc.library/NIPCInquiryA nipc.library/PingEntity nipc.library/ReplyTransaction nipc.library/SetEntityAttrsA nipc.library/WaitEntity nipc.library/WaitTransaction nipc.library/AbortTransaction nipc.library/AbortTransaction NAME AbortTransaction -- Abort an attempted transaction. SYNOPSIS AbortTransaction(transaction) A1 VOID AbortTransaction(struct Transaction *); FUNCTION Aborts a Transaction that was previously started by a call to BeginTransaction(). INPUTS transaction - Pointer to the Transaction to abort. RESULT If the transaction hadn't already been completed (or failed), it will be immediately aborted, and placed on the local Entity. EXAMPLE NOTES Because local Transactions are passed by reference, a transaction sent to a local Entity can be in such a state (being processed) where another process may be referencing them. To ensure that a Transaction is either aborted or completed, an AbortTransaction() call should be followed by a WaitTransaction(). If the transaction given has already completed (or failed), no action will be taken. BUGS SEE ALSO WaitTransaction(), DoTransaction(), BeginTransaction(), CheckTransaction() nipc.library/AddRoute nipc.library/AddRoute NAME AddRoute -- Add a route/gateway for a network SYNOPSIS success = AddRoute(network,gateway,hops,ttl) d0 d0 d1 d2 d3 BOOL AddRoute(ULONG,ULONG,UWORD,WORD); FUNCTION Adds a route for a given network to NIPC's routing tables. Gateway tells NIPC what gateway to use for that network, and hops is the maximum number of hops to use to get to the network. 'ttl' is 'time to live' for the route. This parameter is currently ignored, and -1 must be passed for ttl. INPUTS network - network number this route is for gateway - the gateway machine on that knows how to talk to 'network' hops - maximum number of hops for packets going to 'network' ttl - time to live. Must currently be set to -1. RESULT success - true for success, false for failure to add the route. EXAMPLE NOTES BUGS SEE ALSO DeleteRoute() nipc.library/AllocNIPCBuff nipc.library/AllocNIPCBuff NAME AllocNIPCBuff -- Allocate and initialize a NIPCBuff structure SYNOPSIS nipcbuff = AllocNIPCBuff(entries) D0 D0 struct NIPCBuff *AllocNIPCBuff(entries); FUNCTION This function is used to allocate an NIPCBuff structure for use with transaction data areas. Note that this function only allocates the NIPCBuff structure, initializes it, and possibly adds a number of NIPCBuffEntry's to it. No data area is allocated. INPUTS entries - The number of NIPCBuffEntry's that should be placed in the NIPCBuff structure. RESULT nipcbuff - Pointer to a newly allocated and initialized NIPCBuff structure or NULL if the NIPCBuff or the number of NIPCBuffEntry structures couldn't be allocated. EXAMPLE NOTES You MUST use this function for allocating NIPCBuff structures, or innocent memory will get overwritten. BUGS SEE ALSO FreeNIPCBuff(), <envoy/nipc.h> nipc.library/AllocNIPCBuffEntry nipc.library/AllocNIPCBuffEntry NAME AllocNIPCBuffEntry -- Allocate and initialize a NIPCBuffEntry structure SYNOPSIS entry = AllocNIPCBuffEntry() D0 struct NIPCBuffEntry *AllocNIPCBuffEntry(); FUNCTION This function is used to allocate an NIPCBuffEntry structure for use with NIPCBuff structures. Note that this function only allocates the NIPCBuffEntry structure, and clears it. No data area is allocated. INPUTS None RESULT entry - Pointer to a newly allocated and initialized NIPCBuffEntry structure or NULL if the NIPCBuffEntry couldn't be allocated. EXAMPLE NOTES You MUST use this function for allocating NIPCBuffEntry structures, or innocent memory will get overwritten. BUGS SEE ALSO FreeNIPCBuffEntry(), <envoy/nipc.h> nipc.library/AllocTransactionA nipc.library/AllocTransactionA NAME AllocTransactionA -- Allocate a transaction structure. SYNOPSIS transaction = AllocTransactionA(taglist) D0 A0 struct Transaction *AllocTransactionA(struct TagItem *); struct Transaction *AllocTransaction(tag1, tag2, tag3, ...); FUNCTION This function will attempt to create a Transaction structure for the user. INPUTS taglist -- A pointer to a list of tags defining options and requirements for the structure. TRN_AllocReqBuffer: Attempts to allocate a request buffer for you of the size in the ti_Data field of this TagItem. (default: no request buffer) TRN_AllocRespBuffer: Attempts to allocate a response buffer for you of the size in the ti_Data field of this TagItem. (default: no response buffer) TRN_ReqDataNIPCBuff: TRN_RespDataNIPCBuff: These Tags are used to tell nipc.library that either trans_ResponseData or trans_RequestData are pointers to NIPCBuff structures. "Normal" programmers won't need to use this feature. A NULL taglist will yield the defaults which are no allocations and no NIPCBuff structures. RESULT transaction -- If conditions permit, AllocTransaction() will return a pointer to a Transaction structure. If the library is unable to either allocate memory or meet the requirements set by the tags passed, the function will return a NULL. EXAMPLE NOTES You are completely free to allocate your own buffer space for either a request or a response buffer. If done, you are also responsible for freeing them. BUGS SEE ALSO nipc.library/AppendNIPCBuff nipc.library/AppendNIPCBuff NAME AppendNIPCBuff -- Append one NIPCBuff structure to another SYNOPSIS result = AppendNIPCBuff(first, second) D0 A0 A1 struct NIPCBuff *AppendNIPCBuff(struct NIPCBuff *, struct NIPCBuff *); FUNCTION This function may be used to append the data in one NIPCBuff to another NIPCBuff. Essentially, it just removes the NIPCBuffEntry's from one NIPCBuff and adds them to the other NIPCBuff (in order). After this function completes, the second NIPCBuff will be empty. INPUTS first- Pointer to the NIPCBuf structure to be appended to. second - Pointer to the NIPCBuff structure to be appended. RESULT result - Pointer to the first NIPCBuff EXAMPLE NOTES BUGS SEE ALSO <envoy/nipc.h> nipc.library/BeginTransaction nipc.library/BeginTransaction NAME BeginTransaction -- Start an NIPC Transaction SYNOPSIS BeginTransaction(dest_entity,src_entity, transaction) A0 A1 A2 VOID BeginTransaction(struct Entity *,struct Entity *, struct Transaction *); FUNCTION Attempts to begin a transaction (described appropriately by the transaction structure) to a given entity. INPUTS dest_entity - An abstract data type - a "magic cookie" - that identifies the destination entity. (From FindEntity().) src_entity - An abstract data type - a "magic cookie" - that identifies the source entity. (From CreateEntity().) transaction - a pointer to the Transaction to start. RESULT None. EXAMPLE NOTES After this function begins, the Transaction structure passed becomes the property of the nipc.library, and CANNOT be freed until this Transaction returns to the source Entity. Once the Transaction returns onto the local Entity, the programmer should check trans_Error, to verify that it completed properly. Because data transmission isn't an instantaneous operation, a limit must be imposed on exactly how many transactions can be queued up at any given time. Otherwise, it would be possible for an application program to overflow the throughput of any given networking protocol, occupying all available memory. If the underlying networking protocol becomes overloaded, subsequent calls to BeginTransaction() may block until the networking protocol is no longer overwhelmed. BUGS SEE ALSO DoTransaction(), CheckTransaction(), WaitTransaction(), AbortTransaction(), <envoy/nipc.h> nipc.library/CheckTransaction nipc.library/CheckTransaction NAME CheckTransaction -- Check whether a transaction has completed or not. SYNOPSIS status = CheckTransaction(transaction); D0 A1 BOOL CheckTransaction(struct Transaction *); FUNCTION Provides a mechanism for determining whether a Transaction previously queued with BeginTransaction() has completed. The function will return TRUE if the Transaction is complete (or failed), and FALSE if the Transaction is still in progress. INPUTS transaction - a pointer to a Transaction structure, which describes the details of this specific Transaction. RESULT None. EXAMPLE NOTES CheckTransaction() will return TRUE if the Transaction has never been sent (unlike CheckIO(), which doesn't take this situation into account). BUGS SEE ALSO DoTransaction(), BeginTransaction(), WaitTransaction(), AbortTransaction() nipc.library/CopyFromNIPCBuff nipc.library/CopyFromNIPCBuff NAME CopyFromNIPCBuff -- Copy block of memory out of a NIPCBuff structure SYNOPSIS actual = CopyFromNIPCBuff(src, dest, srcoffset, length) D0 A0 A1 D0 D1 ULONG CopyFromNIPCBuff(struct NIPCBuff *, UBYTE *, ULONG, ULONG); FUNCTION This function is used to copy one NIPCBuff to another. The number of bytes actually copied will be returned. If there isn't enough space in the destination buffer, then actual will be less than length. INPUTS src - Pointer to the NIPCBuf structure to be copied from. dest - Pointer to the NIPCBuff structure to be copied to. dstoffset - Offset into dest buffer. length - Number of bytes to copy. RESULT actual - Number of bytes actually copied. EXAMPLE NOTES This function does not modify any of the fields in the destination NIPCBuff structure or its NIPCBuffEntries. It will abide by the existing values of nbe_Offset and nbe_Length. The upshot of this is that if you want the entire data area referenced by a NIPCBuffEntry to be copied to, you should do the following: ... nbe->nbe_Offset = 0; nbe->nbe_Length = nbe->nbe_PhysicalLength; ... BUGS Before version 40.7, this function may not work correctly due to a bug in NIPCBuffPointer, except when the source offset is zero. SEE ALSO <envoy/nipc.h> nipc.library/CopyNIPCBuff nipc.library/CopyNIPCBuff NAME CopyNIPCBuff -- Copy a NIPCBuff structure SYNOPSIS actual = CopyNIPCBuff(src, dest, srcoffset, dstoffset, length) D0 A0 A1 D0 D1 D2 ULONG CopyNIPCBuff(struct NIPCBuff *, struct NIPCBuff *, ULONG, ULONG, ULONG); FUNCTION This function is used to copy one NIPCBuff to another. The number of bytes actually copied will be returned. If there isn't enough space in the destination buffer, then actual will be less than length. INPUTS src - Pointer to the NIPCBuf structure to be copied from. dest - Pointer to the NIPCBuff structure to be copied to. srcoffset - Offset into src buffer. dstoffset - Offset into dest buffer. length - Number of bytes to copy. RESULT actual - Number of bytes actually copied. EXAMPLE NOTES This function does not modify any of the fields on the src or data NIPCBuff structures or their NIPCBuffEntries. It will abide by the current values of nbe_Offset and nbe_Length on both the source and desitnation buffers. The upshot of this is that if you want the entire data area referenced by a NIPCBuffEntry to be copied from/to, you should do the following: ... nbe->nbe_Offset = 0; nbe->nbe_Length = nbe->nbe_PhysicalLength; ... BUGS Before version 40.7, this function may not work correctly due to a bug in NIPCBuffPointer, except when both source and destination offsets are zero. SEE ALSO <envoy/nipc.h> nipc.library/CopyToNIPCBuff nipc.library/CopyToNIPCBuff NAME CopyToNIPCBuff -- Copy block of memory into a NIPCBuff structure SYNOPSIS actual = CopyToNIPCBuff(src, dest, dstoffset, length) D0 A0 A1 D0 D1 ULONG CopyToNIPCBuff(UBYTE *, struct NIPCBuff *, ULONG, ULONG); FUNCTION This function is used to copy data from a block of memory into a NIPCBuff. If there isn't enough space in the destination buffer, then actual will be less than length. INPUTS src - Pointer to the block of memory to be copied from. dest - Pointer to the NIPCBuff structure to be copied to. dstoffset - Offset into destination buffer. length - Number of bytes to copy. RESULT actual - Number of bytes actually copied. EXAMPLE NOTES This function does not modify any of the fields in the destination NIPCBuff structure or its NIPCBuffEntries. It will abide by the existing values of nbe_Offset and nbe_Length. The upshot of this is that if you want the entire data area referenced by a NIPCBuffEntry to be copied to, you should do the following: ... nbe->nbe_Offset = 0; nbe->nbe_Length = nbe->nbe_PhysicalLength; ... BUGS Before version 40.7, this function may not work correctly due to a bug in NIPCBuffPointer, except when the destination offset is zero. SEE ALSO <envoy/nipc.h> nipc.library/CreateEntityA nipc.library/CreateEntityA NAME CreateEntityA -- Creates an Entity for communication. SYNOPSIS myentity = CreateEntityA(taglist) D0 A0 struct Entity *CreateEntityA(struct TagItem *); struct Entity *CreateEntity(tag1, tag2, tag3, ...); FUNCTION This function allows you to create an Entity for one endpoint for communication. Given the appropriate tags, you may declare that this entity is public - and therefore can be located by FindEntity(). INPUTS taglist -- a list of tags that declare items such as the Entity name (which is only necessary for public Entities), signal bits, etc. The following tags are defined: ENT_Name: Allows the user to declare the name for this entity. This name must be unique -- and if an Entity of similar name already exists, CreateEntity() will return NULL. (default: no provided name) ENT_Public: If included, this entity is _public_, and can be found by FindEntity() call. To declare an entity public, you must also declare the entity name. (default: private) ENT_Signal: Defines that when something arrives at this entity, the given signal bit (bit number, not mask) should be set. (Useful when you intend to maintain a LOT of entities - more than possible to allocate a single signal bit for each. In this method, a large number of entities share the signal bit. The downside is that every entity with that bit must be checked when the bit is found set.) (default: FALSE) ENT_AllocSignal: Asks that CreateEntity() allocate a signal bit from the current context, and set it whenever the entity receives any data, to set that bit. The ti_Data field of this TagItem must be a pointer to a ULONG which CreateEntity will fill in with the bit number, such that you know what bit number to Wait() on. If you provide a NULL as the ti_Data entry, you will not be informed of the signal bit number. (default: signal not allocated) A NULL taglist will provide the defaults. RESULT entity -- a 'magic cookie' that defines your entity, or NULL for failure EXAMPLE NOTES ENT_Signal and ENT_AllocSignal are mutually exclusive. ENT_Public requires that you also provide ENT_Name; the converse, however, is not true. BUGS SEE ALSO DeleteEntity() nipc.library/DeleteEntity nipc.library/DeleteEntity NAME DeleteEntity -- Delete an Entity SYNOPSIS DeleteEntity(entity); A0 VOID DeleteEntity(struct Entity *); FUNCTION DeleteEntity() is the converse of CreateEntity(). It removes the entity from NIPC lists that it may have been attached to, frees up any resources attached to this Entity that were allocated by CreateEntity(), and frees up the actual Entity structure. If NULL is passed as the argument, no action will be taken. INPUTS entity -- a 'magic cookie' that defines your Entity RESULT None. EXAMPLE NOTES If an attempt is made to DeleteEntity() an Entity that has been found (via FindEntity()), but not lost (via LoseEntity()), the Entity being deleted will be maintained by NIPC until all references to it no longer exist. (The same behavior should arguably occur for an Entity on which previously sent Transactions are yet to return.) IMPORTANT WARNING: Use DeleteEntity() ONLY on Entities created with CreateEntity(). Do NOT use DeleteEntity() on Entities created with FindEntity()!! BUGS SEE ALSO CreateEntityA(), LoseEntity() nipc.library/DeleteRoute nipc.library/DeleteRoute NAME DeleteRoute -- Remove a route/gateway for a network SYNOPSIS DeleteRoute(network) d0 VOID DeleteRoute(ULONG); FUNCTION Removes a route for a given network from NIPC's routing tables. INPUTS network - network number to remove the route for RESULT EXAMPLE NOTES BUGS SEE ALSO AddRoute() nipc.library/DoTransaction nipc.library/DoTransaction NAME DoTransaction -- Begin a Transaction, and wait for it to complete. SYNOPSIS DoTransaction(dest_entity,src_entity,transaction) A0 A1 A2 VOID DoTransaction(struct Entity *, struct Entity *, struct Transaction *); FUNCTION Processes an entire Transaction; it sends the request to the host Entity and awaits the response, or returns at any point because of an error. INPUTS dest_entity - An abstract data type - a "magic cookie" - that identifies the destination entity. (From FindEntity().) src_entity - An abstract data type - a "magic cookie" - that identifies the destination entity. (From CreateEntity().) transaction - a pointer to the Transaction to complete. RESULT None. EXAMPLE NOTES DoTransaction() causes the current context to go into a Wait() state until the Transaction is complete (or cannot be completed. After a DoTransaction() call, the trans_Error field should be checked to verify that the Transaction was properly completed. DoTransaction(), like WaitTransaction() is potentially dangerous, and should be used carefully. If no trans_Timeout value is included, and a server never replies the Transaction (for an unknown reason), DoTransaction() can conceivably wait forever. BUGS SEE ALSO BeginTransaction(), <envoy/nipc.h> nipc.library/FindEntity nipc.library/FindEntity NAME FindEntity -- Locate a specific entity on a certain host SYNOPSIS remote_entity = FindEntity(hostname,entityname,src_entity,errorptr) D0 A0 A1 A2 A3 struct Entity *FindEntity(STRPTR, STRPTR, struct Entity *,ULONG *); FUNCTION Attempts to locate a certain entity on a given host. If you pass a NULL for the entityname, FindEntity will interpret that as "the local machine". INPUTS hostname -- pointer to a null-terminated string declaring the host name of the machine on which you expect to find an Entity named the same as 'entityname'. entityname -- pointer to a null-terminated string declaring the name of a public entity. src_entity -- an Entity returned by CreateEntity() that you wish to use as the 'near' side of a communications path. errorptr -- a pointer to a ULONG in which FindEntity() will provide detailed error information in the event of a FindEntity() failure. If a NULL pointer is passed, no detailed error information will be available. RESULT remote_entity -- NULL if the given Entity cannot be found. Otherwise, the magic cookie describing the Entity that you found. EXAMPLE NOTES If you do a FindEntity to a different machine and it succeeds, you have no guarantee that the remote machine's Entity will continue to exist. Because of this, you should check all returned Transactions for error status - if a Transaction to a remote Entity fails because the nipc.library can no longer find the remote Entity, the transaction will be returned as errored. Regardless of what happens, every SUCCESSFUL FindEntity() REQUIRES an associated LoseEntity(). Since the FindEntity() establishes a communications link between the source and destination Entities, it's -dependant- on the source. Therefore, do not DeleteEntity() the source entity before LoseEntity()'ing. BUGS SEE ALSO LoseEntity() nipc.library/FreeNIPCBuff nipc.library/FreeNIPCBuff NAME FreeNIPCBuff -- Free a NIPCBuff structure SYNOPSIS FreeNIPCBuff(buff) A0 VOID FreeNIPCBuff(struct NIPCBuff *); FUNCTION This function is used to free a NIPCBuff structure and any NIPCBuffEntry structures contained in it. Note that the data areas refereced by the NIPCBuffEntry's will not be freed. INPUTS buff - Pointer to the NIPCBuf structure to be freed. RESULT None EXAMPLE NOTES You MUST use this function for freeing NIPCBuff structures, or memory loss will occur. BUGS SEE ALSO AllocNIPCBuff(), <envoy/nipc.h> nipc.library/FreeNIPCBuffEntry nipc.library/FreeNIPCBuffEntry NAME FreeNIPCBuffEntry -- Free a NIPCBuffEntry structure SYNOPSIS FreeNIPCBuffEntry(entry) A0 VOID FreeNIPCBuffEntry(struct NIPCBuffEntry *); FUNCTION This function is used to free a NIPCBuffEntry structure. Note that the data area referenced by the NIPCBuffEntry structure will not be freed. INPUTS entry - Pointer to the NIPCBuffEntry structure to be freed. RESULT None EXAMPLE NOTES You MUST use this function for freeing NIPCBuffEntry structures, or memory loss will occur. BUGS SEE ALSO AllocNIPCBuffEntry(), <envoy/nipc.h> nipc.library/FreeTransaction nipc.library/FreeTransaction NAME FreeTransaction -- Free a previously allocated Transaction structure. SYNOPSIS FreeTransaction(transaction) A1 VOID FreeTransaction(struct Transaction *); FUNCTION Transaction structures created by AllocTransaction() (which ought be ALL of them), must be deallocated with FreeTransaction(). FreeTransaction() frees only the Transaction structure and any portions of the structure that were allocated by the AllocTransaction() function. INPUTS transaction - a pointer to the Transaction structure to free if NULL, no action is taken. RESULT None. EXAMPLE NOTES Don't try to free anything that wasn't allocated by AllocTransaction(). BUGS SEE ALSO AllocTransactionA() nipc.library/GetEntityAttrsA nipc.library/GetEntityAttrsA NAME SetEntityAttrsA -- request the attributes of an Entity. (37.106) SetEntityAttrs -- varargs stub for GetEntityAttrsA(). (37.106) SYNOPSIS numProcessed = GetEntityAttrsA(entity, tagList) A0 A1 ULONG GetEntityAttrsA(struct Entity *, struct TagItem *); numProcessed = GetEntityAttrs(entity, firsttag, ...) ULONG GetEntityAttrs(struct Entity *, Tag, ...); FUNCTION Retrieve the attributes of a specified Entity, according to the attributes chosen in the tag list. For each entry in the tag list, ti_Tag indentifies the attribute, and ti_Data is a pointer to the long variable where you wish the result to be stored. INPUTS entity - An Entity, created by CreateEntityA() tagList - pointer to an array of tags. TAGS ENT_NameLength - Declare the size of your ENT_Name buffer. (MUST be in the same taglist as ENT_Name!) ENT_Name - Find the name of an Entity; ti_Data points to an ENT_NameLength sized buffer. Cannot be used without ENT_NameLength. ENT_Public - Determine whether an Entity is Public or not. (TRUE implies PUBLIC, FALSE implies PRIVATE.) ENT_Signal - Determine what signal bit (if any) is attached to the given Entity. (-1 implies "none", other signal bit number is stored in the long pointed to by ti_Data.) RESULT numProcessed - the number of attributes successfully filled in. NOTES Attributes not included in the above taglist are unreadable. This function exists only in revision 37.106 and later. SEE ALSO SetEntityAttrsA() nipc.library/GetEntityName nipc.library/GetEntityName NAME GetEntityName -- Get the ASCII name associated with an Entity. SYNOPSIS status = GetEntityName(entity,stringptr,available); A0 A1 D0 BOOL GetEntityName(STRPTR, STRPTR, ULONG); FUNCTION Given a pointer to a string, the length of the string data area, and an entity magic-cookie, this function will attempt to return the name associated with the Entity. INPUTS entity - A magic cookie, identifying an Entity. stringptr - A pointer to a section of memory that you'd like the name copied into. available - The size of the above string area. RESULT status - Either TRUE or FALSE. Note that even if you've referenced an entity, over a network - it's possible that resolving what the correct name is COULD fail. EXAMPLE NOTES If the given Entity has no name, the string "UNNAMED ENTITY" will be returned. BUGS SEE ALSO nipc.library/GetHostName nipc.library/GetHostName NAME GetHostName -- Get the name of a specific machine. SYNOPSIS status = GetHostName(entity,stringptr,available) D0 A0 A1 D0 BOOL GetHostName(struct Entity *, STRPTR, ULONG); FUNCTION Given a pointer to a string, the length of the string data area, and an Entity magic-cookie, this function will attempt to return the ASCII name associated with the host that the Entity is on. INPUTS entity - A magic cookie, identifying an Entity. (If NULL, the string returned will be either LocalRealm:LocalHost, or simply LocalHost -- depending on whether the local machine is in a realm-based environment or not.) stringptr - A pointer to a section of memory that you'd like the name copied into. available - The size of the above string area. RESULT status - Either TRUE or FALSE. Note that even if you've referenced an Entity over a network, it's possible that resolving the name COULD fail. EXAMPLE NOTES BUGS Prior to version 40.9, GetHostName() would actually append LocalHost to the buffer stringptr if a NULL entity was passed. Workaround: Put an initial null byte into the buffer before calling this function. SEE ALSO nipc.library/GetTransaction nipc.library/GetTransaction NAME GetTransaction -- receive the next Transaction waiting on an Entity SYNOPSIS transaction = GetTransaction(entity) D0 A0 struct Transaction *GetTransaction(struct Entity *); FUNCTION GetTransaction() attempts to remove the next available Transaction from the given Entity. INPUTS entity -- An entity created by CreateEntity(). (Not from FindEntity() as you're NOT allowed to read from someone else's Entity.) RESULT transaction -- NULL if no Transactions are waiting, a pointer to a Transaction structure otherwise. EXAMPLE NOTES After a successful GetTransaction(), you should check the trans_Type field of a transaction to determine whether it's a request, or a returned failed request/response that was previously BeginTransaction()'d from this Entity. A transaction returned by GetTransaction will have TYPE_SERVICING for a request. Do not confuse this with TYPE_REQUEST! WARNING: Note that nipc.library might change how the transaction data was packed on the transfer. You MUST check if the request and response data buffers are NIPC buffers or not _before_ referencing them. Check the trans_Flags field for this. Important: While nipc.library will not break any data from the source entity into smaller pieces, it may combine them into larger pieces. So if you find that the data is now an NIPC buffer, you must use NIPCBuffPointer() to find the start of your data chunks. Don't make any further assumptions. Just adhere to these rules and you should be safe. BUGS SEE ALSO BeginTransaction(), DoTransaction(), WaitTransaction(), ReplyTransaction(), NIPCBuffPointer(), <envoy/nipc.h> nipc.library/LoseEntity nipc.library/LoseEntity NAME LoseEntity -- Free up any resources attached from a FindEntity. SYNOPSIS LoseEntity(entity) A0 VOID LoseEntity(struct Entity *); FUNCTION This will merely free up any resources allocated with a successful FindEntity() call. INPUTS entity - An abstract data type - a "magic cookie" - that identifies an Entity. NULL for no action. RESULT None. EXAMPLE NOTES LoseEntity() should only be used on Entities returned by FindEntity(). BUGS SEE ALSO CreateEntity(), DeleteEntity() nipc.library/NIPCBuffLength nipc.library/NIPCBuffLength NAME NIPCBuffLength -- Determine the amount of data stored in a NIPCBuff SYNOPSIS length = NIPCBuffLength(buff) D0 A0 ULONG NIPCBuffLength(struct NIPCBuff *); FUNCTION This function may be used to determine the total amount of data stored in the NIPCBuff structure. Note that this does not return the total capacity of all of the NIPCBuffEntry's. INPUTS buff - Pointer to a NIPCBuf structure RESULT length - Number of bytes stored in buff. EXAMPLE NOTES BUGS SEE ALSO <envoy/nipc.h> nipc.library/NIPCBuffPointer nipc.library/NIPCBuffPointer NAME NIPCBuffPointer -- Get a pointer to data inside a NIPCBuff SYNOPSIS data = NIPCBuffPointer(buff, buffentry, offset) D0 A0 A1 D0 UBYTE *NIPCBuffPointer(struct NIPCBuff *, struct NIPCBuffEntry **, ULONG); FUNCTION This function may be used to find a particular piece of data within a NIPCBuff structure. Returns a pointer to the data item, and a pointer to the NIPCBuffEntry that contains that item. INPUTS buff - Pointer to a NIPCBuf structure offset - Offset into the NIPCBuff buffentry - Pointer to a struct NIPCBuffEntry * to be modified RESULT data - Points to the byte at offset bytes into buff. buffentry - Points to the NIPCBuffEntry that contains "data". EXAMPLE NOTES BUGS Versions of nipc.library prior to 40.7 had a problem with offsets that exactly matched the length of a BuffEntry, and returned a pointer past the end of the BuffEntry previous to the one it should have. Earlier autodocs had the offset and buffentry arguments reversed. This autodoc matches the published function prototype now. SEE ALSO <envoy/nipc.h> nipc.library/NIPCInquiryA nipc.library/NIPCInquiryA NAME NIPCInquiryA -- Start a nipc network query SYNOPSIS success=NIPCInquiryA(hook, maxTime, maxResponses, tagList) D0 A0 D0 D1 A1 BOOL NIPCInquiryA(struct Hook *, ULONG, ULONG, APTR); success=NIPCInquiry(hook, maxTime, maxResponses, firsttag, ...) BOOL NIPCInquiry(struct Hook *, ULONG, ULONG, Tag, ...); FUNCTION Starts an NIPC Network Inquiry. This function can be used to gather data about a single machine, or to gather data for a number of machines. Multiple types of inquiries may be made using this function. Please see below for a description of the types of queries and the types of information you may gather. The Hook is called for each packet returned from hosts on the network. Depending on how specific your query is, you may or may not get more than one packet. When either maxTime seconds or maxResponses packets have been received, your Hook will be called with a null ParamPckt parameter. If your Hook routine decides that it has all of the information it needs, it may return FALSE. This will cause nipc.library to abort the NIPCInquiry() call. When the Hook is called, the "Object" parameter will be a pointer to the Task structure for the task or process that called the NIPCInquiryA() function. This is useful if you want to signal the calling task when the query is complete. The Hook "Message" parameter will be a pointer to an array of TagItem structures that contain the query response data from each responding host. If the query fails for some reason, either due to illegal parameters or to a lack of resources, NIPCInquiryA() will return FALSE. In this case, your Hook function will never be called, so be careful. INPUTS hook(struct Hook *) - Pointer to a Hook structure to be called for each response. maxTime(ULONG) - The maximum number of seconds allowed for the query. This is the absolute maximum time allowed. Nipc.library does not add anything to this value. maxResponses(ULONG) - The maximum number of responses that you will accept from the network. tagList(struct TagItem *) - Pointer to an array of TagItem structures. below. TAGS The Tags currently defined for NIPCInquiryA() are: QUERY_IPADDR (ULONG) - This tag is used for querying a machine for it's Network IP address. Note: This function is provided purely for diagnostic purposes. Do NOT depend on this tag being available in the future. MATCH_IPADDR (ULONG) - Query a host with the specified IP address address. Please see the note above regarding QUERY_IPADDR. QUERY_REALMS (STRPTR) - Query a realmserver for the names of all known Realms. MATCH_REALM (STRPTR) - Only query hosts that are in a specific Realm. QUERY_HOSTNAME (STRPTR) - Query a host for it's name. MATCH_HOSTNAME (STRPTR) - Only query the host with the specified hostname. QUERY_SERVICES (STRPTR) - Query a host or hosts for the names of all services on each machine. MATCH_SERVICE (STRPTR) - Only query hosts that have a specific service specified by the Tag. QUERY_ENTITIES (STRPTR) - Query a host or hosts for the names of all public entities on each machine. MATCH_ENTITY (STRPTR) - Query only hosts that have a public entity specified by the Tag. QUERY_OWNER (STRPTR) - This Tag is currently ignored. MATCH_OWNER (STRPTR) - This Tag is currently ignored. QUERY_ATTNFLAGS (ULONG) - This Tag allows you to find out what bits are set in ExecBase->AttnFlags. MATCH_ATTNFLAGS (ULONG) - Query only hosts that have the specified bits set in ExecBase->AttnFlags. QUERY_LIBVERSION (VOID) - This Tag is currently ignored. MATCH_LIBVERSION (VOID) - This Tag is currently ignored. QUERY_CHIPREVBITS (ULONG) - This Tag alllows you to find out what bits are set in GfxBase->ChipRevBits0. Note: Only the lower 8 bits of the ULONG are used. MATCH_CHIPREVBITS (ULONG) - Query only hosts that have the specified bits set in GfxBase->ChipRevBits0. QUERY_MAXFASTMEM (ULONG) - Query a machine for it's maximum amount of FAST memory. MATCH_MAXFASTMEM (ULONG) - Query only hosts with at least the specified amount of FAST memory. QUERY_AVAILFASTMEM (ULONG) - Query a machine for the amount of free FAST memory it has available. MATCH_AVAILFASTMEM (ULONG) - Query only those hosts that have at least the specified amount of FAST memory available. QUERY_MAXCHIPMEM (ULONG) - Query a machine for it's maximum amount of installed CHIP memory. MATCH_MAXCHIPMEM (ULONG) - Query only those hosts that have at least the specified amount of CHIP ram installed. QUERY_AVAILCHIPMEM (ULONG) - Query a machine for the amount of free CHIP memory it has available. MATCH_AVAILCHIPMEM (ULONG) - Query only those hosts that have at least the specified amount of CHIP memory available. QUERY_KICKVERSION (ULONG) - Query a machine for the version and revision of Kickstart it is running. MATCH_KICKVERSION (ULONG) - Query only those hosts that are running at least the specified version and revision of Kickstart. QUERY_WBVERSION (ULONG) - Query a machine for the version and revision of Workbench it is running. MATCH_WBVERSION (ULONG) - Query only those hosts that are running at least the specified version and revision of Workbench. RESULT success - Success/failure indication. EXAMPLES Query all hosts in realm "Software" for their Hostname, CPU type, Fast memory installed and Kickstart version: NIPCInquiry(myhook, \* The hook to call *\ 2, \* 2 seconds max *\ 15, \* 15 responses max *\ MATCH_REALM,"Software", QUERY_HOSTNAME, 0, QUERY_ATTNFLAGS, 0, QUERY_MAXFASTMEM, 0, QUERY_KICKVERSION, 0, TAG_DONE); The Hook would then get called for each host that responds. An example TagList passed to the hook might be: MATCH_REALM,"Software", QUERY_HOSTNAME,"A2500 Test". QUERY_ATTNFLAGS, AFF_68010|AFF_68020|AFF_68881, QUERY_MAXFASTMEM, 4194304, (4 Megs) QUERY_KICKVERSION, 2425007, (VERSION <<16 | REVISION) TAG_DONE --- Query a server for all services it has available NIPCInquiry(myhook, 2, 2, MATCH_REALM,"Marketing", MATCH_HOSTNAME,"Market Server", QUERY_SERVICES,0, TAG_DONE) A possible response might be: MATCH_REALM,"Marketing", MATCH_HOSTNAME,"Market Server", QUERY_SERVICES,"EnvoyFileSystem", QUERY_SERVICES,"EnvoyPrinterService", QUERY_SERVICES,"ConferenceService", TAG_DONE) NOTES This function is considered very low-level and is provided for network diagnostic functions. You should probably be using the functions supplied in envoy.library to do network queries. These will provide "wrappers" for the most common types of queries. nipc.library/PingEntity nipc.library/PingEntity NAME PingEntity -- Calculate the round-trip time between two Entities SYNOPSIS elapsedtime = PingEntity(entity, limit) D0 A0 D0 ULONG PingEntity(struct Entity *, ULONG); FUNCTION INPUTS entity - A magic cookie, identifying an Entity. limit - Maximum number of microseconds to wait for a response. RESULT elapsedtime - Total number of microseconds elapsed between attempting to query the Entity, and a response returning. If -1L, no response was received in the given timeout interval. Local Entities will return 0 for elapsed time. EXAMPLE NOTES BUGS SEE ALSO nipc.library/ReplyTransaction nipc.library/ReplyTransaction NAME ReplyTransaction -- Reply a Transaction. SYNOPSIS ReplyTransaction(transaction) A1 VOID ReplyTransaction(struct Transaction *); FUNCTION This causes a Transaction received from another Entity to be returned to the sender. You may return data with the Transaction as well. (See the Transaction structure definition for details.) INPUTS transaction -- Pointer to a Transaction structure that was returned by a previous GetTransaction() call. RESULT None. EXAMPLE NOTES BUGS SEE ALSO GetTransaction() nipc.library/SetEntityAttrsA nipc.library/SetEntityAttrsA NAME SetEntityAttrsA -- change the attributes of an Entity. (37.106) SetEntityAttrs -- varargs stub for SetEntityAttrsA(). (37.106) SYNOPSIS SetEntityAttrsA(entity, tagList) A0 A1 VOID SetEntityAttrsA(struct Entity *, struct TagItem *); SetEntityAttrs(entity, firsttag, ...) VOID SetEntityAttrs(struct Entity *, Tag, ...); FUNCTION Change the attributes of a specified Entity, according to the attributes chosen in the tag list. If an attribute is not provided in the tag list, it's value remains unchanged. INPUTS entity - An Entity, created by CreateEntityA() tagList - pointer to an array of tags providing optional extra parameters, or NULL. TAGS ENT_Public - Set/Reset the public state of an Entity. TRUE = PUBLIC, FALSE = PRIVATE. ENT_Release - Refuse ownership of this Entity; deallocates any signal bits created with ENT_AllocSignal. (Not those passed in with ENT_Signal!) Use in conjunction with ENT_Inherit to pass an Entity between processes. ENT_Inherit - Declares ownership of an Entity that has previously been set with ENT_Release. If a signal bit is necessary, this call should be used with ENT_Signal or ENT_AllocSignal. ENT_Signal - Set the signal bit of the Entity to the bit value specified by ti_Data. If a bit was previously allocated by ENT_AllocSignal, it will be freed. ENT_AllocSignal - Allocate a signal bit for this Entity. ti_Data points to a longword where you wish the bit number to be stored, or NULL. If a signal bit was previously allocated by ENT_AllocSignal, it will be freed, regardless of the success/failure of this attribute modification. ENT_TimeoutLinks - Defines that any link entities connected to this Entity should be automatically removed after ti_Data seconds of inactivity. 0 seconds is defined as meaning "infinite" timeouts, which is the default on Entity creation. NOTES Attributes not included in the above taglist are unchangable. This function exists only in revision 37.106 and later. SEE ALSO GetEntityAttrsA() nipc.library/WaitEntity nipc.library/WaitEntity NAME WaitEntity -- Waits for a Transaction to arrive at an Entity. SYNOPSIS WaitEntity(localentity) A0 VOID WaitEntity(struct Entity *); FUNCTION WaitEntity() simply causes the current process to Wait() until something arrives at the entity. INPUTS entity - An abstract data type - a "magic cookie" - that identifies an Entity. RESULT None. EXAMPLE NOTES This is potentially dangerous - if nothing ever arrives at this Entity, this function will never return. Unless warrented, the caller should be using Wait() with a signal mask. BUGS SEE ALSO GetTransaction() nipc.library/WaitTransaction nipc.library/WaitTransaction NAME WaitTransaction -- Waits for a Transaction to complete. SYNOPSIS WaitTransaction(transaction) A1 VOID WaitTransaction(struct Transaction *); FUNCTION Waits for the given transaction to complete, or return as failed. INPUTS transaction -- a pointer to a Transaction structure. RESULT None. EXAMPLE NOTES - When doing networked transactions, if for any reason the remote machine fails to send a response, (but no network problem exists) and you did not supply a timeout value in trans_Timeout, WaitTransaction() can Wait() forever. - If you attempt to WaitTransaction() on a transaction that has already been responded to, WaitTransaction() will return immediately. - If the given Transaction has not already completed, WaiTransaction() will wait for it to complete, and then -remove- the Transaction from the source Entity. (In other words, you don't need to GetTransaction() it off of the Entity.) BUGS SEE ALSO BeginTransaction(), DoTransaction(), exec.library/Wait()