home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 June: Reference Library / Dev.CD Jun 94.toast / Periodicals / develop / develop Issue 11 / develop 11 code / The NetWork Project / NetWork Programmer's Stuff / NetWork.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-07-15  |  11.6 KB  |  323 lines  |  [TEXT/MPS ]
  1. /* © Copyright 1989,90,91 The NetWork Project, StatLab Heidelberg.
  2.    © Copyright 1989,90,91 Joachim Lindenberg, Karlsruhe,
  3.                           Günther Sawitzki, Heidelberg. All rights reserved. */
  4.  
  5. /* NetWork.h */
  6.  
  7. /*
  8.   This header file is yet incomplete, but it interfaces to the most
  9.   important functions that are available in the NetWork library.
  10.   
  11.   WARNING : This file is translated by hand, it may be in error or
  12.   simply out of date. Consult the pascal version if in doubt.
  13.   
  14.   See SampleTool.c & UDPTransport.c for examples on using NetWork with C.
  15. */
  16.  
  17. /*
  18.   This library does not support code without an A5 world. If you want to use
  19.   NetWork from other code (non application, non tool), you´ll have to use
  20.   control calls to the driver directly. Contact us if you need help with that.
  21.   
  22.   The library uses a call to NetWork Processor to find out whether this process
  23.   is already known to NetWork. If it is, it is assumed to be launched by NetWork
  24.   by means of a message or idle time launch, and the type and signature are confirmed.
  25.   If it is not known, the process is registered using the default type and the
  26.   application´s signature. The default type is pMaster unless you set pDefault to
  27.   something different. It is allowed to use pSlave or pLocal even if not launched
  28.   automatically, and the process will be subject to the rules of slave/local
  29.   processes in that case.
  30. */
  31.  
  32. #ifndef __NetWork__
  33. #define __NetWork__
  34.  
  35. #include <Types.h>
  36. #include <OSUtils.h>
  37.  
  38. /*    =============================================================    */
  39.  
  40. /* global declarations - general use */
  41.  
  42. /* general error messages - many of them are never returned to user processes.
  43.   Also other operating system error codes may bubble up. */
  44.  
  45. /* some of these codes should be reconsidered, also some of them could be more specific */
  46.  
  47. #define    eQueEmpty         -31000    /* no more messages avail - out of memory */
  48. #define ePrio2Big         -31001    /* priority information too big */
  49. #define eNoSuchMsg         -31002    /* invalid or NIL message reference, no message avail (GET) */
  50. #define eNotLaunched     -31003    /* destination process does not exist - NOT USED */
  51. #define eAbortMsg         -31004    /* message transfer aborted */
  52. #define eProcTableFull      -31005    /* process table full (Init/Exit) */
  53. #define eNoSuchProcess     -31006    /* specified process unknown */
  54. #define eNoMoreDynamics     -31007    /* maximum number of dynamic ids exceeded */
  55. #define eLaunchFailed     -31008    /* launch failed - NOT USED */
  56. #define eInvalid         -31009    /* local message transfer aborted */
  57. #define eSizeLimit         -31010    /* message larger than supported by transport - AppleTalk broadcast - eMsg2Big */
  58. #define eVersion         -31011    /* version of library/driver/transport/system */
  59. #define eProtType         -31012    /* no transport, invalid network address - Dispatcher */
  60. #define eLoopback         -31013    /* discard of broadcasted message - NEVER returned to user */
  61. #define eTransportDown     -31014    /* transport system not available - AppleTalk */
  62. #define eCmdSequence     -31015    /* cmd sequencing error - bug of NetWork Processor or Dispatcher */
  63. #define eProtIndex         -31016    /* protocol index out of range - GetTransport */
  64. #define eProcessExists     -31017    /* creator registered for a DIFFERENT process - process mgmt */
  65. #define eProcessIndex     -31018    /* invalid process index - GetIndexedProcess */
  66. #define eProcessType     -31019    /* process type illegal or does not match launch - process mgmt */
  67. #define eRestartListen     -31020    /* a listener handled a request for more data,
  68.                                        and requires a restart therefore - AppleTalk - NEVER returned to user */
  69. #define eMsgTimeout         -31021    /* maximum message lifetime exceeded - AppleTalk */
  70. #define eNoSignature     -31022    /* couldn´t obtain signature of application file - Library */
  71. #define eMsgLockFailed     -31023    /* couldn´t lock message - NOT USED */
  72. #define eSigTableFull     -31024    /* signature table full */
  73. #define eSigRegistered     -31025    /* signature already registered */
  74. #define eSigNotRegistered  -31026    /* signature not registered */
  75. #define eProcMgmtError   -31027    /* internal error */
  76. #define eSourceSig         -31028    /* source signature wrong in Send/Post */
  77. #define eSourceAddr         -31029    /* source address wrong in Send/Post */
  78.  
  79. /* capas defined */
  80.  
  81. #define cMustExist    0x080000000;    /* process must exist -- don´t launch */
  82.     
  83. /* idle monitor states - see NetWork TN 12 Idle Monitor States */
  84.  
  85. #define    imBusy        0
  86. #define    imIdle        1
  87. #define    imActive    2
  88. #define    imLoaded    3
  89.     
  90. /* process types - see NetWork Communications */
  91.  
  92. #define pUnknown      0;
  93. #define pSlave          1;
  94. #define pLocal          2;
  95. #define pMaster          3;
  96.     
  97. /* transport system constants */
  98.  
  99. /* major command codes */
  100.  
  101. #define tGeneral 0x00
  102. #define tListen 0x10
  103. #define tGet 0x20
  104. #define tAccept 0x30
  105. #define tSend 0x40
  106. #define tPost 0x40
  107.  
  108. /* minor command codes */
  109.  
  110. #define tStart 0x00
  111. #define tTimeout 0x0c
  112. #define tTimeout1 0x0d
  113. #define tAbort 0x0e
  114. #define tAbort1 0x0f
  115.  
  116. /* misc command codes */
  117.  
  118. #define tInit 0x00
  119. #define tTickle 0x01
  120. #define tDeregister 0x02
  121. #define tRegister 0x03
  122. #define tShutdown 0x0f
  123.  
  124. /* useful values */
  125.  
  126. #define tMajorMask 0x0f0
  127. #define tMinorMask 0x00f
  128.     
  129. typedef struct MsgAddr MsgAddr;
  130. typedef struct MsgRec MsgRec, *MsgPtr;
  131. typedef struct TransportRecord TransportRecord, *TransportPtr;
  132.  
  133. struct MsgAddr {
  134.     long            a, p;
  135. };
  136.  
  137. /*    except for MsgUserRefCon all of the components are READ ONLY */
  138.  
  139. struct MsgRec {
  140.     MsgPtr            MsgLink;
  141.     void *            Msg2ndLink;
  142.     short            MsgResult;
  143.     unsigned char    MsgFlags, MsgCmd;
  144.     long            MsgTicks;
  145.  
  146.     long            MsgUserRefCon;
  147.     long            MsgReserved1, MsgReserved2, MsgReserved3;
  148.     TransportPtr    MsgTrpPtr;
  149.     long            MsgTrpRefCon;
  150.  
  151. /*    message header information - all of this is transported to the destination */
  152.  
  153.     MsgAddr            MsgSource,
  154.                     MsgDest,
  155.                     MsgReply;
  156.     long            MsgCapasVerb,
  157.                     MsgReference,
  158.                     MsgPrioSize,
  159.                     MsgCoreSize;
  160.     Ptr                MsgPrioPtr,
  161.                     MsgCorePtr;
  162. };
  163.     
  164. /* transport system */
  165.  
  166. struct TransportRecord {
  167.     TransportPtr    TransportLink;                /* link to next transport in queue                     */
  168.     void *            TransportProc;                /* pointer to definition proc - overlays magic        */
  169.     StringHandle    TransportName;                /* name of resource - overlays header vers & size    */
  170.     long            TransportID;                /* transport protocol (unique) signature            */
  171.     StringHandle    TransportDomain;            /* transport domain dependent string                */
  172.     long            TransportAddr;                /* local address of this transport system            */
  173.     long            TransportBCAddr;            /* this transports broadcast address                */
  174.     long            TransportStart;                /* first valid address on this transport            */
  175.     long            TransportEnd;                /* last valid address                                */
  176.     short            TransportMsgSize;            /* size of MsgRecord for this transport system        */
  177.     short            TransportListensRequested;    /* see NetWork Transports for a discussion            */
  178.     short            TransportListensStarted;    /* of these three fields.                            */
  179.     short            TransportListensCompleted;
  180.     long            TransportReserved;            /* reserved for future use                            */
  181.     void *            TransportVars;                /* private vars, may be longint, ptr, or handle        */
  182.     MsgPtr *        TransportMsgQHead;            /* pointer to head of message queue                    */
  183.     void *            TransportAttnRtn;            /* pointer to attn routine (supplied by NetWork)    */
  184. };
  185.  
  186.  
  187. /* =============================================================    */
  188.  
  189. /*    conversion & logging 
  190.     Note: all strings are PASCAL string pointers */
  191.  
  192. pascal void AddrToString (MsgAddr *, StringPtr);
  193. pascal void MsgToString (MsgPtr, StringPtr);
  194. pascal void LogString (StringPtr);
  195. pascal void LogStrTime (StringPtr);
  196. pascal void LogMsg (StringPtr, MsgPtr);
  197. pascal void CheckError (StringPtr, OSErr);
  198.  
  199. /* =============================================================    */
  200.  
  201. /* general utilities */
  202.  
  203. pascal void ProgramBreak (StringPtr);    /* drop into debugger if one is installed -- SADE ? (new calls) -- to go? */
  204. pascal Boolean Visible (void);            /* display a user interface ? */
  205. pascal Boolean Spare (void);            /* this returns the setting of the spare flag */
  206. pascal long TimeStamp (void);            /* randomized timestamp, should be unique for each call -- (sample code) */
  207.  
  208. /* =============================================================    */
  209.  
  210. /* idle manager */
  211.  
  212. pascal void PreventIdle (void);         /* tell NetWork that we are doing useful stuff - to go ? */
  213. pascal short IdleMonitorState (void);    /* state of idle monitor */
  214. pascal Boolean Idle (void);                /* is the local system idle ? */
  215. pascal long IdleTicks (void);             /* number of ticks we have been idle, < 0 if busy */
  216.  
  217. /* =============================================================    */
  218.  
  219. /*    transport interface */
  220.  
  221. pascal Boolean IsLocal (long);            /* shouldn´t be used. to go ? */
  222. pascal OSErr GetTransport (TransportPtr *, short);     /* to go ? */
  223. pascal QHdrPtr GetTransportQHdr (void);
  224. pascal OSErr InstallTransport (TransportPtr Trp);
  225. pascal OSErr RemoveTransport (TransportPtr Trp);
  226.  
  227. /* =============================================================    */
  228.  
  229. /* address management - to go ? */
  230.  
  231. pascal Boolean EqAddr (MsgAddr *, MsgAddr *);
  232. pascal Boolean EqNode (MsgAddr *, MsgAddr *);
  233. pascal MsgAddr SetMsgAddr (long, long);
  234. pascal MsgAddr GetNetWorkAddr (void);
  235.  
  236.  
  237. /* =============================================================    */
  238.  
  239. /* process management */
  240. /*    most of the process management is done implicitly, these may
  241.     be the things you are interested in. */
  242.  
  243. extern long pFileSignature, pProcessSignature;    /* valid after InitNetWork */
  244.  
  245. pascal Boolean Master (void);
  246.  
  247. pascal OSErr GetProcessType (long, short *);
  248. pascal OSErr SetProcessType (long, short);
  249. pascal OSErr GetIndProcess (long *, short);
  250. pascal OSErr LaunchLocalApplication (long *, short, long, StringPtr);
  251.  
  252. /* =============================================================    */
  253.  
  254. /* message management - remove GetMsg, rename GetThisMsg to GetMsg. */
  255.  
  256. /* DumpMessages dumps all currently active messages - is this useful to applications ? */
  257.  
  258. pascal void  DumpMessages(void);
  259.  
  260. /*    AvailableMsg returns the number of available messages - to go */
  261.  
  262. pascal int AvailableMsg(void);
  263.  
  264. /*    the following pascal void  returns 0 if the Msg has been transferred completely
  265.     < 0 if there was an error, > 0 indicates that the Msg is still transferred 
  266.     or waiting. */
  267.  
  268. pascal OSErr MsgStatus (MsgPtr); /* to go ? */
  269.  
  270. /*    SignalMsg checks to see if a new or old message needs handling */
  271.  
  272. pascal OSErr SignalMsg (MsgPtr *); /* useful for non app code */
  273.  
  274. /*    GetMsg checks to see if there is a new message available. */
  275.  
  276. pascal OSErr  GetIndexedMsg ( MsgPtr *,
  277.                     short,    /*0=1*/
  278.                     Ptr, 
  279.                     long);
  280.  
  281. /*    GetMsg gets a message that has been signaled */
  282.  
  283. pascal OSErr GetMsg (MsgPtr, Ptr, long);
  284.  
  285. /*    FlushMsg discards all received messages not "Got" except those with DontFlushMask set */
  286.  
  287. pascal OSErr FlushMsg (long);
  288.  
  289. /*    AcceptMsg will tell the transport system to receive the message and store 
  290.     it at the memory passed. */
  291.  
  292. pascal OSErr AcceptMsg (MsgPtr, Ptr, long);
  293.  
  294. /*    PostMsg generates a new message that will be sent. It does not make a copy
  295.     of the information that is referenced. */
  296.  
  297. pascal OSErr PostMsg (MsgPtr *, TransportPtr, long, long, MsgAddr *, MsgAddr *, Ptr, long, Ptr, long);
  298.  
  299. /*    SendMsg uses the information in RefMsg to post a new message. All of the 
  300.     fields must be filled in. The message posted is returned in NewMsg. */
  301.     
  302. pascal OSErr SendMsg (MsgPtr, MsgPtr *);
  303.  
  304. /*    ForwardMsg forwards a message to the same or another process on the same machine.
  305.     Don´t call DestroyMsg for a message you forwarded except if you forward to yourself.
  306.     ForwardMsg may be called after a GetMsg, but all buffer references will be removed */
  307.     
  308. pascal OSErr ForwardMsg (MsgPtr, long);
  309.  
  310. /*    DestroyMsg gets rid of a message. This possibly kills a transfer */
  311.  
  312. pascal OSErr DestroyMsg (MsgPtr);
  313.  
  314. /* =============================================================    */
  315.  
  316. /* initialization and termination. Call InitNetWork before use of anything
  317.   within this unit. Call ExitNetWork as part of your cleanup sequence. */
  318.  
  319. pascal OSErr InitNetWork (short);
  320. pascal OSErr ExitNetWork (void);
  321.  
  322. #endif
  323.