home *** CD-ROM | disk | FTP | other *** search
/ Hall of Fame / HallofFameCDROM.cdr / prog1 / zmnp11.lzh / ZMNP.DOC < prev    next >
Text File  |  1990-02-08  |  19KB  |  661 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. [XYZ]MODEM and MNP2 library interface description.
  7. Giles Todd  February 8, 1990
  8.  
  9.  1.0  Basic async comms functions.
  10.  
  11.     1.1  int connect (int rate, int data, int parity, int stop, int
  12.          port, int handshake)
  13.  
  14.          where
  15.  
  16.          rate      is the speed of the physical connection:
  17.                     1 = 110 bps
  18.                     2 = 300 bps
  19.                     3 = 600 bps (no MNP)
  20.                     4 = 1200 bps
  21.                     5 = 2400 bps
  22.                     6 = 4800 bps (no MNP)
  23.                     7 = 9600 bps (no MNP)
  24.                     8 = 19200 bps (no MNP)
  25.                     9 = 38400 bps (no MNP, may not work on some PCs)
  26.                    10 = 56000 bps (no MNP, may not work on some PCs)
  27.                    11 = 115200 bps (no MNP, may not work on some PCs)
  28.  
  29.          data      is the number of data bits (5..8)
  30.  
  31.          parity    is the selected parity
  32.                    0 = NONE
  33.                    1 = ODD
  34.                    3 = EVEN
  35.                    5 = MARK
  36.                    7 = SPACE
  37.  
  38.                    8 bit data, no parity is recommended for use with
  39.                    the file transfer protocols.
  40.  
  41.                    If MNP is to be used, the only valid settings are:
  42.                    8 bit data, no parity
  43.                    7 bit data, even, odd, mark or space parity.
  44.  
  45.          stop      the number of stop bits (1 or 2)
  46.                    NB: if 5 data bits are used, 1 1/2 stop bits are
  47.                    automatically selected.
  48.  
  49.          port      is the COM port number (1 and 2 only)
  50.  
  51.          handshake is the hardware handshaking flag
  52.                    0 = no RTS/CTS handshaking
  53.                    1 = use RTS/CTS handshaking
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                         1
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.          This function returns an integer with the following meaning:
  73.                      0 = success, 8250 initialised
  74.                    -64 = invalid rate
  75.                    -65 = invalid data
  76.                    -66 = invalid parity
  77.                    -67 = invalid stop
  78.                    -68 = invalid port
  79.                    -69 = invalid handshake
  80.  
  81.          This function initialises the 8250 and the PC interrupt
  82.          vectors.
  83.  
  84.     1.2  void hangup (void)
  85.  
  86.          Hangs up the physical link by dropping DTR.  If using an MNP
  87.          link, call mnpdisconnect () before calling this function.
  88.  
  89.     1.3  void disconnect (void)
  90.  
  91.          Hangs up the physical link and restores the original interrupt
  92.          environment and 8250 settings.  If using an MNP link, call
  93.          mnpdisconnect () before calling this function.  Use before
  94.          exiting from your program.
  95.  
  96.     1.4  int send (unsigned char *sndbuf, unsigned int buflen)
  97.  
  98.          where
  99.  
  100.          sndbuf    points to the buffer where the data to be sent is
  101.                    stored.
  102.  
  103.          buflen    is the maximum number of data bytes to be sent.
  104.  
  105.          The function's return value is a count of the bytes actually
  106.          sent.  This may differ from the count requested to be sent.
  107.  
  108.          send (NULL, 0) may be used to flush the output buffer.
  109.  
  110.          This function may only be used _outside_ an MNP connection.
  111.          Use the mnpsend () equivalent during an MNP connection.
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                         2
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.     1.5  int receive (unsigned char *rcvbuf, unsigned int buflen)
  139.  
  140.          where
  141.  
  142.          rcvbuf    points the the user receive buffer.  This buffer must
  143.                    be at least as long as buflen.
  144.  
  145.          buflen    is the number of bytes to copy into the user receive
  146.                    buffer.
  147.  
  148.          The function's return value is is a count of the bytes actually
  149.          copied into the receive buffer.  This may differ from the count
  150.          requested to be copied. 
  151.  
  152.          This function may only be used _outside_ an MNP connection.
  153.          Use the mnpreceive () equivalent during an MNP connection.
  154.  
  155.     1.6  void bufstat (unsigned short *s_free, unsigned short *r_ready)
  156.  
  157.          where
  158.  
  159.          s_free    points to a variable which is filled in with the
  160.                    number of bytes free in the transmit buffer
  161.  
  162.          r_ready   points to a variable which is filled in with the
  163.                    number of bytes ready to be read from the receive
  164.                    buffer
  165.  
  166.          This function returns information about the state of the
  167.          transmit and receive buffers.
  168.  
  169.          This function may only be used _outside_ an MNP connection.
  170.          Use the mnpstatus () equivalent during an MNP connection.
  171.  
  172.     1.7  unsigned char linestat (void)
  173.  
  174.          returns a copy of the 8250 line status register.
  175.  
  176.          bit set   meaning
  177.               0    Rx ready
  178.               1    overrun error
  179.               2    parity error
  180.               3    framing error
  181.               4    BREAK detect
  182.               5    Tx buffer empty
  183.               6    Tx empty
  184.               7    Always 0
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                         3
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.     1.8  unsigned char modemstat (void)
  205.  
  206.          returns a copy of the 8250 modem status register.
  207.  
  208.              bit   meaning
  209.               0    if set, CTS changed since last read
  210.               1    if set, DSR changed since last read
  211.               2    if set, RI changed since last read
  212.               3    if set, DCD changed since last read
  213.               4    absolute state of CTS input
  214.               5    absolute state of DSR input
  215.               6    absolute state of RI input
  216.               7    absolute state of DCD input
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                         4
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  2.0  MNP level 2 functions.
  271.  
  272.       Please note that after an MNP link has been established (but
  273.       not after it has been terminated), it must be maintained by
  274.       calling one of mnpsend (), mnpreceive (), mnpstatus () or
  275.       mnpbreak () every 250ms or so (recommended although not
  276.       critical).  If no data is being transferred and your program is
  277.       waiting for user input, this may be achieved by calling
  278.       mnpstatus () on each pass through a keyboard polling loop.
  279.       [XYZ]MODEM file transfers on an MNP link will perform this
  280.       polling automatically.  Future versions of this library may
  281.       perform this polling automatically as part of a timer interrupt
  282.       service routine.
  283.  
  284.       Note also that the mnpxxx () data transfer and status functions
  285.       are only valid if the call to mnpconnect () succeeds.
  286.  
  287.     2.1  int mnpconnect (unsigned int mode)
  288.  
  289.          where
  290.  
  291.          mode      is the 'role' to play:
  292.                    0 = link initiator (caller)
  293.                    1 = link acceptor (answerer)
  294.  
  295.          This function returns an integer with the following meaning:
  296.                      0 = success (link established)
  297.                    -64 = failure, unknown error
  298.                    -65 = failure, timeout
  299.                    -66 = failure, no carrier
  300.                    -67 = failure, bad data format
  301.                    -70 = failure, incompatible MNP
  302.                    -72 = failure, remote protocol error
  303.  
  304.          This function is used to establish an error corrected link.  It
  305.          is called after the physical link has been established (i.e.
  306.          carrier present) by a call to connect (), the sending of the
  307.          appropriate dialling sequence via send () and the detection of
  308.          carrier (either by receiving a CONNECT message from the modem
  309.          or by reading the modem status).  It can take up to five
  310.          seconds for the MNP negotiation to complete.  Note that this
  311.          function _must_ be called within four seconds of the physical
  312.          connection being made.
  313.  
  314.     2.2  void mnpdisconnect (void)
  315.  
  316.          This function is used to terminate the error corrected link.
  317.          It must be called just prior to hanging up with a disconnect ()
  318.          or hangup () call.
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                         5
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.     2.3  int mnpsend (unsigned char *sndbuf, unsigned int buflen)
  337.  
  338.          where
  339.  
  340.          sndbuf    points to the buffer where the data to be sent is
  341.                    stored.
  342.  
  343.          buflen    is the maximum number of data bytes to be sent.
  344.  
  345.          If the function's return value is positive, it is a count of
  346.          the bytes actually sent.  This may differ from the count
  347.          requested to be sent.  A negative return code indicates an
  348.          error as follows:
  349.                    -64 = link terminated, retransmission limit exceeded
  350.                    -65 = link terminated, unable to send
  351.                    -66 = link terminated, no carrier
  352.                    -67 = link terminated, remote disconnect
  353.  
  354.          mnpsend (NULL, 0) may be used to flush the output buffer.
  355.  
  356.     2.4  int mnpreceive (unsigned char *rcvbuf, unsigned int buflen)
  357.  
  358.          where
  359.  
  360.          rcvbuf    points the the user receive buffer.  This buffer must
  361.                    be at least as long as buflen.
  362.  
  363.          buflen    is the number of bytes to copy into the user receive
  364.                    buffer.
  365.  
  366.          If the function's return value is positive, it is a count of
  367.          the bytes actually copied into the receive buffer.  This may
  368.          differ from the count requested to be copied.  A negative
  369.          return code indicates an error as follows:
  370.                    -64 = link terminated, retransmission limit exceeded
  371.                    -65 = link terminated, unable to send
  372.                    -66 = link terminated, no carrier
  373.                    -67 = link terminated, remote disconnect
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                         6
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.     2.5  void mnpstatus (struct link_stat_blk *stat)
  403.  
  404.          where
  405.  
  406.          struct link_stat_blk               /* defined in ZMNP.H */
  407.               {
  408.               unsigned short p_status;
  409.               unsigned short l_status;
  410.               unsigned short s_count;
  411.               unsigned short r_count;
  412.               unsigned short all_sent;
  413.               } *stat;
  414.  
  415.          This function fills in the fields of the user's status
  416.          structure as follows:
  417.  
  418.          p_status  physical connection status
  419.                    0 = not connected (no carrier)
  420.                    1 = connected (carrier present)
  421.  
  422.          l_status  MNP link status
  423.                    0 = MNP link not established
  424.                    1 = MNP link established
  425.  
  426.          s_count   the number of bytes free in the MNP transmit buffer.
  427.                    This indicates the maximum number of bytes which can
  428.                    be sent by a mnpsend () call.
  429.  
  430.          r_count   the maximum number of bytes which can be read by a
  431.                    mnpreceive () call.
  432.  
  433.          all_sent  data sent and successfully acknowledged flag.
  434.                    0 = all data not sent
  435.                    1 = all data sent
  436.  
  437.     2.6  int mnpbreak (void)
  438.  
  439.          Sends a break signal to the remote DTE.  The return code is
  440.          interpreted as follows:
  441.  
  442.                      0 = break initiated
  443.                    -64 = link terminated, retransmission limit exceeded
  444.                    -65 = link terminated, unable to send
  445.                    -66 = link terminated, no carrier
  446.                    -67 = link terminated, remote disconnect
  447.                    -75 = break not supported (remote did not negotiate
  448.                          break support for this link)
  449.                    -76 = previous break still in progress
  450.  
  451.          Note that mnpbreak () is only valid when sent to a MNP modem.
  452.          The current version of this library does not yet support
  453.          application notification of a received break condition.
  454.  
  455.  
  456.  
  457.                                         7
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  3.0  [XYZ]MODEM functions.
  469.  
  470.     3.1  int sendfile (char protocol, char *options, char *filenames[],
  471.          void (*reporter) (int type, void *data))
  472.  
  473.          Sends files.  Returns 0 if files transmitted successfully
  474.          otherwise returns a negative error code:
  475.               -1   invalid option
  476.               -2   user abort
  477.               -3   no carrier
  478.  
  479.          Parameters:
  480.  
  481.          protocol  the file transfer protocol:
  482.                         'z' = ZMODEM
  483.                         'y' = YMODEM batch
  484.                         'x' = XMODEM
  485.  
  486.          options   a null terminated string of characters denoting
  487.                    various protocol options:
  488.                         '+' = append file to existing destination file
  489.                               (ZMODEM)
  490.                         'a' = convert <NL> to <CR/NL> in ASCII file
  491.                         'b' = binary file transfer
  492.                         'c' = send command, wait for completion
  493.                               (ZMODEM).  The command string should be
  494.                               delimited by '#' characters.
  495.                         'd' = change '.' to '/' in pathnames
  496.                               (YMODEM/ZMODEM)
  497.                         'e' = escape all control characters (ZMODEM)
  498.                         'f' = send full pathname (YMODEM/ZMODEM)
  499.                         'i' = send command, no wait for completion
  500.                               (ZMODEM).  The command string should be
  501.                               delimited by '#' characters.
  502.                         'k' = 1024 byte packets (YMODEM)
  503.                         'L' followed by a number = limit subpacket
  504.                               length to number bytes.  The number must
  505.                               be followed by a whitespace character
  506.                               (ZMODEM)
  507.                         'l' followed by a number = limit frame length
  508.                               to number bytes (l >= L).  The number must
  509.                               be followed by a whitespace character
  510.                               (ZMODEM)
  511.                         'n' = send only if source newer (ZMODEM)
  512.                         'N' = send only if source newer or longer
  513.                               (ZMODEM)
  514.                         'o' = use 16 bit CRC instead of 32 bit (ZMODEM)
  515.                         'p' = don't overwrite existing target (ZMODEM)
  516.                         'r' = resume interrupted file transfer (ZMODEM)
  517.                         'q' = quiet (no progress report)
  518.                         'u' = erase source file after transmission
  519.  
  520.  
  521.  
  522.  
  523.                                         8
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.                         'v' = provide debugging information.  More 'v's,
  535.                               more debug info (9 max).  Information
  536.                               is appended to the file ZMODEM.LOG in
  537.                               the current directory.
  538.                         'w' followed by a number = set window to number
  539.                               bytes.  The number must be followed by a
  540.                               whitespace character (ZMODEM)
  541.                         'Y' = overwrite existing destination file but
  542.                               don't send if no existing destination file
  543.                               (ZMODEM)
  544.                         'y' = overwrite existing destination file
  545.                               unconditionally (ZMODEM)
  546.  
  547.          filenames an array of filenames to be sent.  The last string in
  548.                    this array should be the null string ("") which acts
  549.                    as an end marker.  NB: only one file name is
  550.                    permitted if the XMODEM protocol is chosen.
  551.  
  552.          reporter  a pointer to a user function which makes progress
  553.                    reports.  The type parameter of this function
  554.                    indicates whether the data parameter points to
  555.                    character or numeric data.  If type = 0, data points
  556.                    to the filename string.  If type = 1, data points to
  557.                    an unsigned long which gives the number of bytes
  558.                    transferred so far.  If type = 2, data points to a
  559.                    text string (usually an error message).  If you just
  560.                    want to use the default progress reporting (or no
  561.                    progress reporting with the 'q' option), set this
  562.                     parameter to NULL.
  563.                    NB: the user report function should return as quickly
  564.                    as possible to avoid losing any MNP link.
  565.  
  566.     3.2  int getfile (char protocol, char *options, char *filename, void
  567.          (*reporter) (int type, void *data))
  568.  
  569.          Receives files.  Returns 0 if files received successfully
  570.          otherwise returns a negative error code:
  571.               -1   invalid option
  572.               -2   user abort
  573.               -3   no carrier
  574.  
  575.          Parameters:
  576.  
  577.          protocol  the file transfer protocol:
  578.                         'z' = ZMODEM
  579.                         'y' = YMODEM batch
  580.                         'x' = XMODEM
  581.  
  582.                    If the ZMODEM or YMODEM protocols are chosen, the
  583.                    filename parameter will be ignored and should be
  584.                    set to NULL.  The filename parameter _must_ be
  585.                    supplied for an XMODEM transfer.
  586.  
  587.  
  588.  
  589.                                         9
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.          options   a null terminated string of characters denoting
  601.                    various protocol options:
  602.                         'a' = ASCII transfer
  603.                         'b' = binary transfer
  604.                         'c' = XMODEM/CRC (XMODEM)
  605.                         'e' = escape control characters (ZMODEM)
  606.                         'i' = disallow remote commands (ZMODEM)
  607.                         'q' = quiet (no progress report)
  608.                         'v' = provide debugging information.  More 'v's,
  609.                               more debug info (9 max).  Information
  610.                               is appended to the file ZMODEM.LOG in
  611.                               the current directory.
  612.  
  613.          filename  the filename for an XMODEM receive.  For YMODEM batch
  614.                    and ZMODEM, this parameter should be set to NULL.
  615.  
  616.          reporter  a pointer to a user function which makes progress
  617.                    reports.  The type parameter of this function
  618.                    indicates whether the data parameter points to
  619.                    character or numeric data.  If type = 0, data points
  620.                    to the filename string.  If type = 1, data points to
  621.                    an unsigned long which gives the number of bytes
  622.                    transferred so far.  If type = 2, data points to a
  623.                    text string (usually an error message).  If you just
  624.                    want to use the default progress reporting (or no
  625.                    progress reporting with the 'q' option), set this
  626.                     parameter to NULL.
  627.                    NB: the user report function should return as quickly
  628.                    as possible to avoid losing any MNP link.
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.                                         10
  656.  
  657.  
  658.  
  659.  
  660.  
  661.