OS/2 Professional

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

/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / com / zocdev / pip / tech.doc < prev

Wrap

Text File | 1993-12-11 | 11.2 KB | 454 lines

This document discusses technical matters of the Plug-In- Protocol (PIP) interface. No (C) of any kind applies - implementation of PIP in clients or terminals is free. However sole host of truth about the Plug-In-Protocol is me. If you plan to implement the terminal side of the TAP interface contact me for sample sources. Keep OS/2 interesting for the people, develop for OS/2!! Markus Schmidt Introduction: ============== Each PIP is a DLL that begins with the name PIP. The name shall not be longer than eight characters to be compatible with the FAT file system. Every PIP-DLL has to export five fuctions: int pipIntro(PIP_SOCKET *, PIP_PLUG * ) int pipInit(PIP_SOCKET *, PIP_PLUG * ) int pipSetup(PIP_SOCKET *, PIP_PLUG * ) int pipSend(PIP_SOCKET *, PIP_PLUG *, char *, char **) int pipReceive(PIP_SOCKET *, PIP_PLUG *, char*, char **) int pipCleanup(PIP_SOCKET *, PIP_PLUG *) Each function receives as parameters a pointer to a socket structure and a pointer to a plug structure. The socket structure is initialized by ZOC and must not be modified by the plug (thus being defined as const). The plug gets its connection to socket functions through the socket structure. The plug structure is used by both the plug and the socket. Export Functions: ================= pipIntro(): ----------- The pipIntro() functions is called once, when the DLL is loaded into memory. It fills the fields PlugName, PlugDescription, PlugType, PlugBits and PlugPipVersion fields of the plug stucture to tell the socket what it is capable off. The socket shall not request any services the plug is not capable of, but it is a good idea for the plug not to rely on that. Additionaly the plug can request automatic start of upload or download by filling the PlugAutoUpload and PlugAutoDownload fields of the plug structure. Both fields are zero terminated and must not contain a Carriage Return (0x0D)or a Line Feed (0x0A). pipInitialize(): ---------------- This function is called by the socket before it calls any of the pipSetup(), pipSend() or pipReceive() functions so the plug has a chance to do internal initialisations. Each pipInitialize() is paired with a call to pipCleanup(). pipInitialize() will not be called twice without calling pipCleanup() in between. However the following calling sequences : pipIntro(), pipInitialize(), pipSetup(), pipCleanup(), pipInitialize(), pipSend(), pipCleanup() and pipIntro(), pipInitialize(), pipSetup(), pipSend(), pipCleanup() are both legal. Mostly pipInitialize() will allocate memory to the private pointer of the plug structure and try to initialize it with potential options from the INI file. Calls to pipInitialize() and pipCleanup() will be strictly paired and will not be nested (except if called from different applications as it might occur with every DLL). pipSetup(): ----------- The taks of pipSetup() is to allow the user to defined protocol specific options like transfer mode or something alike. These options should be stored to the OS2.INI file under the application name defined in PIP_INIAPPL under a unique key. pipSend() and pipReceive() shall retrieve the options from OS2.INI because the user will not always call pipSetup() before calling pipSend()/pipReceive(). Further there might have been a pipCleanup(), pipInitialize() call between pipSetup() and pipSend()/pipReceive() as shown above. pipSetup() should check the dlgHwndFrame field from the socket structure to see if it was called from a PM or VIO application and eventually return PIP_ERROR. pipSend()/pipReceive(): ----------------------- This function will be called if the user selected the upload option in the terminal program. According to the bits reported by pipIntro() the socket will supply pointers for path or multipath. Path is a zero terminated string with one filename and optional directory (absolute or realative to the current working directory). Multipath is an array of pointer to such strings with a NULL pointer to end the list. The value of path/multipath is related to the PlugBits: If the plug reports FILEREQUESTER for the current environment (PM/VIO) path and multipath will always be NULL. The plug has to handle file dialogs by itself. If the plug reports SINGLEUPLOAD multipath will always be NULL. Path will contain one zero terminated string of a filename. If the plug reports MULTIPLEUPLOAD path will always be NULL. Multipath will contain one or more pointers to a filename. If the plug reports both SINGLEUPLOAD and MULTIPLEUPLOAD one of path or multipath will be NULL the other containing a value as described above. Transfer protocols that receive the file name from the remote station (e. g. Compuserve B) should report the FILEREQUESTER bit to the socket but should never display one. This way no filerequester is shown and the files can be transferred to/from the default directories as given in the socket parameter structure. The file transfer options shall be retrieved from the OS2.INI file as described under pipInitialize() and pipSetup(). IMPORTANT: To prevent locking of PM and to give the socket opportunity to update timers and other stuff the pipSend/Receive() has to call the CoreLoop() function of the socket at least once a second. Processing of pipReceive() is analog to pipSend(). pipCleanup(): ------------- The pipCleanup() function is the complement to pipInitialize() and will only be called after that. Its task is to free memory and other resources before the DLL might be unloaded. Calls to pipInitialize() and pipCleanup() are strictly paired and will not be nested (except if called from different applications as it might occur with every DLL). Description of PIP_SOCKET: ========================== What follows is a description of the most important fields in the PIP_SOCKET structure. int PipVersion: --------------- Version of the PIP interface the socket uses. Socket and plug will normally be downward compatible. If changes have to be implemented that impair compatibility tha major version number (bit 8 to 4) of PIP_VERSION will change. So compare this field to PIP_VERSION (as defined in PIP.H) with the PIP_COMPATIBLE() macro and report an error if not equal. HAB hab: -------- When running in PM environment this is the anchor block handle of the socket. If zero, you are running under a non-PM Application. HFILE hfComDevice: ------------------- File handle for com device. If zero no modification of com device (mainly serial options) is not allowed. If nonzero the plug may use DosDevIoctl, but shall reset the com device to its initial state when terminating. ULONG ulBaud: ------------- Actual com speed. Will always be supplied by the socket. unsigned char szUploadDir[CCHMAXPATH]: -------------------------------------- Default path for uploads. Never terminated by "\". If empty ("") upload from current directory. May be overriden by directory path in the path/multipath parameters of pipSend()/pipReceive(). So just use this, if path/ multipath is just a filename or a filename with relative path. unsigned char szDownloadDir[CCHMAXPATH]: ---------------------------------------- Default path for downloads. Never terminated by "\". If empty ("") download to the current directory. May be overriden by directory path in the path/multipath parameters of pipSend()/pipReceive(). void ioConPutChar(unsigned char chr): ------------------------------------- Output of one character to the main terminal window. void ioConPutData(unsigned char *pdata, long length): ----------------------------------------------------- Output of a block of character to the main terminal window. int ioSerQueryAvail(void): --------------------------- Query if there are any characters are in the input queue. Returns TRUE or FALSE. int ioSerGetChar(void): ------------------------ Read one character from the serial device. Returns PIP_READ_NODATA (256) if no data available. int ioSerTimedGetChar(int timeout): ------------------------------------ Read one character from the serial device within a given time (timeout is 1/10 seconds). If PIP_READ_NODATA (256) is returned no data arrived within the given time (timeout). void ioSerPutChar(unsigned char chr): ------------------------------------- Write a single character to the com device. void ioSerPutData(unsigned char *pdata, long length): ------------------------------------------------------ Write a block of characters to the com device. void ioSerUngetData(unsigned char *pdata, int length): ------------------------------------------------------ Put characters back into the input queue for later reading. Max length is 16. Must not be used incrementally. void ioSerPutBrk(void): ----------------------- Send a modem break HWND dlgHwndFrame: ------------------ Handle of PM frame window (eg to center upon). Zero for VIO applications, but determine PM/VIO environment from 'hab'. void dlgErrorMsg(unsigned char *txt): ------------------------------------- View an error message. void dlgInfoMsg(unsigned char *txt): ------------------------------------ View an information message. File I/O functions: ------------------- The sockte structure contains pointers to file I/O functions that are wrappers for the stream I/O functions defined by the ANSI standard. These functions are equivalent to the ANSI functions, but additionally send messages to a TAP (see ..\TAP\TECH.DOC). The only difference is the fopen function which has an additional size parameter to indicate the size when opening a file for writing. This field is sent with the TAP_OPENFORXXXX message to an eventual tap. If not available (e.g. for X-Modem) size should be set to zero. When opening a file for reading, size is ignored and calcualated internally void CoreLoop(void): -------------------- Call this function periodically to allow the socket to dispatch messages or update statusline. This function has to be called at least once a second. Otherwise PM might hang.