Amiga ISO Collection/AmigaUtilCD2.iso/Misc/PsionPalmTopConnector.LHA/AmigaNCP09beta/Developer/Autodocs/ncp.doc

Text File | 1994-09-26 | 19.6 KB | 882 lines

TABLE OF CONTENTS

ncp.library/NCP_AbortRead
ncp.library/NCP_AbortWrite
ncp.library/NCP_BeginRead
ncp.library/NCP_BeginWrite
ncp.library/NCP_CheckRead
ncp.library/NCP_CheckWrite
ncp.library/NCP_clnl
ncp.library/NCP_CloseChannel
ncp.library/NCP_Fault
ncp.library/NCP_ibm2iso
ncp.library/NCP_ILONG
ncp.library/NCP_ILONGP
ncp.library/NCP_ILONGPI
ncp.library/NCP_iso2ibm
ncp.library/NCP_IWORD
ncp.library/NCP_IWORDP
ncp.library/NCP_IWORDPI
ncp.library/NCP_LinkRemoteRun
ncp.library/NCP_OpenChannel
ncp.library/NCP_Read
ncp.library/NCP_ReadSig
ncp.library/NCP_WaitRead
ncp.library/NCP_WaitWrite
ncp.library/NCP_Write
ncp.library/NCP_WriteSig
ncp.library/NCP_AbortRead                           ncp.library/NCP_AbortRead

   NAME
    NCP_AbortRead -- abort read currently in progress

   SYNOPSIS
    NCP_AbortRead( channel )
                     A0

    void NCP_AbortRead( APTR )

   FUNCTION
    Aborts the current read request on the given NCP channel.
    Does nothing if no read is pending.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    None.

   EXAMPLE

   NOTES
    Never forget to finish a read request using NCP_WaitRead(),
    or you'll end up in OS hell.

   BUGS
    None known.

   SEE ALSO
    NCP_Read(), NCP_WaitRead(), NCP_CheckRead(), NCP_BeginRead()

ncp.library/NCP_AbortWrite                         ncp.library/NCP_AbortWrite

   NAME
    NCP_AbortWrite -- abort write currently in progress

   SYNOPSIS
    NCP_AbortWrite( channel )
                     A0

    void NCP_AbortWrite( APTR )

   FUNCTION
    Aborts the current write request on the given NCP channel.
    Does nothing if no write is pending.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    None.

   EXAMPLE

   NOTES
    Never forget to finish a write request using NCP_WaitWrite(),
    or you'll end up in OS hell.

   BUGS
    None known.

   SEE ALSO
    NCP_Write(), NCP_WaitWrite(), NCP_CheckWrite(), NCP_BeginWrite()

ncp.library/NCP_BeginRead                           ncp.library/NCP_BeginRead

   NAME
    NCP_BeginRead -- start a read request on the NCP channel.

   SYNOPSIS
    error = NCP_BeginRead( channel, data, datasize )
      D0                     A0      A1       D0

    LONG NCP_BeginRead( APTR, APTR, ULON G);

   FUNCTION
    Queues a read operation on the current NCP channel.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()
    data -- receive buffer
    datasize -- receive buffer size

   RESULT
    error -- either 0 if the read was queued successfully
             or a negative error number

   EXAMPLE

   NOTES
    Only one read request may be queued at a time on a single
    channel. This function fails with NCPE_INUSE if there is
    already a read request outstanding.

   BUGS
    None known.

   SEE ALSO
    NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_CheckRead()

ncp.library/NCP_BeginWrite                         ncp.library/NCP_BeginWrite

   NAME
    NCP_BeginWrite -- start a write request on the NCP channel.

   SYNOPSIS
    error = NCP_BeginWrite( channel, data, datasize )
      D0                     A0      A1       D0

    LONG NCP_BeginWrite( APTR, APTR, ULON G);

   FUNCTION
    Queues a write operation on the current NCP channel.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()
    data -- data buffer
    datasize -- data buffer size

   RESULT
    error -- either 0 if the write was queued successfully
             or a negative error number

   EXAMPLE

   NOTES
    Only one write request may be queued at a time on a single
    channel. This function fails with NCPE_INUSE if there is
    already a write request outstanding.

   BUGS
    None known.

   SEE ALSO
    NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_CheckWrite()

ncp.library/NCP_CheckRead                           ncp.library/NCP_CheckRead

   NAME
    NCP_CheckRead -- check if a read request is still pending

   SYNOPSIS
    status = NCP_CheckRead( channel )
      D0                       A0

    LONG NCP_CheckRead( APTR )

   FUNCTION
    Check if a read request is still pending on the given NCP
    channel.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    status -- FALSE if a read is currently pending,
              TRUE if no request is pending or the current
              request has completed.

   EXAMPLE

   NOTES
    Never forget to finish a read request using NCP_WaitRead(),
    or you'll end up in OS hell.

   BUGS
    None known.

   SEE ALSO
    NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_BeginRead()

ncp.library/NCP_CheckWrite                         ncp.library/NCP_CheckWrite

   NAME
    NCP_CheckWrite -- check if a write request is still pending

   SYNOPSIS
    status = NCP_CheckWrite( channel )
      D0                       A0

    LONG NCP_CheckWrite( APTR )

   FUNCTION
    Check if a write request is still pending on the given NCP
    channel.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    status -- FALSE if a write is currently pending,
              TRUE if no request is pending or the current
              request has completed.

   EXAMPLE

   NOTES
    Never forget to finish a write request using NCP_WaitWrite(),
    or you'll end up in OS hell.

   BUGS
    None known.

   SEE ALSO
    NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_BeginWrite()

ncp.library/NCP_clnl                                     ncp.library/NCP_clnl

   NAME
    NCP_clnl -- clear CR/LF at end of line.

   SYNOPSIS
    NCP_clnl( string )
              A0

    void NCP_clnl( STRPTR );

   FUNCTION
    Clears any CR or LF characters at the end of the string.

   INPUTS
    string -- pointer to string (contents will be modified)

   RESULT
    None.

   EXAMPLE

   NOTES

   BUGS
    None known.

   SEE ALSO

ncp.library/NCP_CloseChannel                     ncp.library/NCP_CloseChannel

   NAME
    NCP_CloseChannel -- close a NCP channel

   SYNOPSIS
    NCP_CloseChannel( channel )
                       A0

   void NCP_CloseChannel( APTR );

   FUNCTION
    Close a NCP channel previously opened by NCP_OpenChannel().
    If this is an active link to the remote machine, it will be
    closed.

   INPUTS
    channel -- channel to close. May be NULL, in which case
               this functions does nothing.

   RESULT
    None.

   EXAMPLE

   NOTES
    An active NCP connection will be dropped about 10s
    after the last channel has been closed.

   BUGS
    None known.

   SEE ALSO
    NCP_OpenChannel()

ncp.library/NCP_Fault                                   ncp.library/NCP_Fault

   NAME
   NCP_Fault -- return localized NCP error string

   SYNOPSIS
   NCP_Fault( code, header, buffer, buffersize );
               D0     A0      A1        D1

   void NCP_Fault( LONG, STRPTR, STRPTR, ULONG );

   FUNCTION
   Returns a localized text string associated with the
   error code.

   INPUTS
   code -- NCP error code
   header -- header to insert before string. May be NULL
   buffer -- buffer to write the error text to
   buffersize -- size of buffer

   RESULT
   None.

   EXAMPLE

   NOTES

   BUGS
   None known.

   SEE ALSO
   dos.library/Fault()

ncp.library/NCP_ibm2iso                               ncp.library/NCP_ibm2iso

   NAME
    NCP_ibm2iso -- convert IBM to ISO charachter

   SYNOPSIS
    isochar = NCP_ibm2iso( ibmchar )
      D0                    D0 0:7

    UBYTE NCP_ibm2iso( UBYTE );

   FUNCTION
    Converts a character from the IBM to the ISO charset.

   INPUTS
    ibmchar -- character of the IBM codeset

   RESULT
    isochar -- equivalent character in the ISO codeset

   EXAMPLE

   NOTES

   BUGS
    None known.

   SEE ALSO

ncp.library/NCP_ILONG                                   ncp.library/NCP_ILONG

   NAME
    NCP_ILONG -- swap bytes in longword

   SYNOPSIS
    slongword = NCP_ILONG( longword )
      D0                     D0

    ULONG NCP_ILONG( ULONG );

   FUNCTION
    Swaps the byte order within the longword.

   INPUTS
    longword -- a 32 bit data word.

   RESULT
    slongword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES

   BUGS
    None known.

   SEE ALSO

ncp.library/NCP_ILONGP                                 ncp.library/NCP_ILONGP

   NAME
    NCP_ILONGP -- swap bytes in longword (pointer version)

   SYNOPSIS
    sword = NCP_ILONGP( longwordp1, longwordp2 )
      D0                    A0          A1

    ULONG NCP_ILONGP( ULONG *, ULONG * );

   FUNCTION
    Swaps the byte order from the longword pointed to by longwordp1
    and places the result in the longword pointed to by longwordp2.

   INPUTS
    longwordp1 -- pointer to source longword
    longwordp2 -- pointer to destination longword

   RESULT
    sword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES
    The longwords don't need to be word aligned.

   BUGS
    The 68020++ version of ncp.library requires the hardware
    to be able to do misaligned word accesses. Some early
    accelerator boards may have problems doing this.

   SEE ALSO

ncp.library/NCP_ILONGPI                               ncp.library/NCP_ILONGPI

   NAME
    NCP_ILONGPI -- swap bytes in longword (in-place pointer version)

   SYNOPSIS
    sword = NCP_ILONGPI( longwordp )
      D0                    A0

    ULONG NCP_ILONGP( ULONG * )

   FUNCTION
    Swaps the byte order within the longword pointed to by longwordp.

   INPUTS
    longwordp -- pointer to longword to swap

   RESULT
    sword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES
    The longword doesn't need to be word aligned.

   BUGS
    The 68020++ version of ncp.library requires the hardware
    to be able to do misaligned word accesses. Some early
    accelerator boards may have problems doing this.

   SEE ALSO

ncp.library/NCP_iso2ibm                               ncp.library/NCP_iso2ibm

   NAME
    NCP_iso2ibm -- convert IBM to ISO charachter

   SYNOPSIS
    ibmchar = NCP_iso2ibm( isochar )
      D0                    D0 0:7

    UBYTE NCP_iso2ibm( UBYTE );

   FUNCTION
    Converts a character from the ISO to the IBM charset.

   INPUTS
    isochar -- character of the ISO codeset

   RESULT
    ibmchar -- equivalent character in the IBM codeset

   EXAMPLE

   NOTES

   BUGS
    None known.

   SEE ALSO

ncp.library/NCP_IWORD                                   ncp.library/NCP_IWORD

   NAME
    NCP_IWORD -- swap bytes in word

   SYNOPSIS
    sword = NCP_IWORD( word )
      D0                D0

    UWORD NCP_IWORD( UWORD );

   FUNCTION
    Swaps the byte order within the word.

   INPUTS
    word -- a 16 bit data word.

   RESULT
    sword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES

   BUGS
    None known.

   SEE ALSO

ncp.library/NCP_IWORDP                                 ncp.library/NCP_IWORDP

   NAME
    NCP_IWORDP -- swap bytes in word (pointer version)

   SYNOPSIS
    sword = NCP_IWORDP( wordp1, wordp2 )
      D0                  A0      A1

    UWORD NCP_IWORDP( UWORD *, UWORD * );

   FUNCTION
    Swaps the byte order from the word pointed to by wordp1
    and places the result in the word pointed to by wordp2.

   INPUTS
    wordp1 -- pointer to source word
    wordp2 -- pointer to destination word

   RESULT
    sword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES
    The words don't need to be word aligned.

   BUGS
    The 68020++ version of ncp.library requires the hardware
    to be able to do misaligned word accesses. Some early
    accelerator boards may have problems doing this.

   SEE ALSO

ncp.library/NCP_IWORDPI                               ncp.library/NCP_IWORDPI

   NAME
    NCP_IWORDPI -- swap bytes in word (in-place pointer version)

   SYNOPSIS
    sword = NCP_IWORDPI( wordp1 )
      D0                   A0

    UWORD NCP_IWORDP( UWORD * )

   FUNCTION
    Swaps the byte order within the word pointed to by wordp.

   INPUTS
    wordp -- pointer to word to swap

   RESULT
    sword -- the same word with the byte order swapped.

   EXAMPLE

   NOTES
    The word doesn't need to be word aligned.

   BUGS
    The 68020++ version of ncp.library requires the hardware
    to be able to do misaligned word accesses. Some early
    accelerator boards may have problems doing this.

   SEE ALSO

ncp.library/NCP_LinkRemoteRun                   ncp.library/NCP_LinkRemoteRun

   NAME
   NCP_LinkRemoteRun -- use the NCP link channel to run a program on
                        the remote machine.

   SYNOPSIS
   error = NCP_LinkRemoteRun( filename, cmdline, cmdlinelen )
   D0                            A0       A1        D0

   LONG NCP_LinkRemoteRun( STRPTR, APTR, ULONG );

   FUNCTION
   Use the LINK supervisor channel to have the remote link
   run a program. No NCP channel needs to be opened in order
   to perform this operation.

   INPUTS
   filename -- file name of the remote program to start
   cmdline -- pointer to command line array. Note that
              EPOC command lines are *NOT* zero terminated.
   cmdlinelen -- length of command line in bytes. May be
                 zero, in which case no command line
                 is transfered.

   RESULT
   error -- either an AmigaNCP specific error code or the
            result code from the remote link.

   EXAMPLE
   Have WORD.APP read the Amiga startup sequence:

       UBYTE cmdline[] = {
        "OANCPTest\000 V TES\000REM::SYS:\S\STARTUP-SEQUENCE\000"
       };
       error = NCP_LinkRemoteRun( "WORD.APP", cmdline, sizeof( cmdline ) );

   NOTES
   See the Psion SDK for more information about using commandlines and
   the LINK process launch feature.

   BUGS
   None known.

   SEE ALSO

ncp.library/NCP_OpenChannel                       ncp.library/NCP_OpenChannel

   NAME
    NCP_OpenChannel -- open a NCP channel to attempt to connect to
                      the remote.

   SYNOPSIS
    channel = NCP_OpenChannel( localname, remotename, flags )
      D0                          A0          A1        D0

    APTR NCP_OpenChannel( STRPTR, STRPTR, ULONG );

   FUNCTION
    Opens an NCP channel. If remotename is not NULL, attempts
    to connect to the remote process and fails with a NULL
    return if the connection could not be made. If remotename
    is NULL, creates a passive channel silently awaiting remote
    connection.

   INPUTS
    localname -- name of local "process"
    remotename -- either NULL for a passive channel or
                  the remote process name which to connect
                  to
    flags -- currently unused, leave at 0

   RESULT
    channel -- pointer to a channel object. NULL in case of
               an error, whereas additional error information
               can be found in IoErr()

   EXAMPLE
    To connect to the remote file server:

       APTR channel;
       channel = NCP_OpenChannel( "TestHost", "SYS$RFSV.*", 0 );


   NOTES
    Opening an active channel will result in an attempt to
    create an NCP connection and fail upon any error (including
    serial failure or inexistance of the remote process).
    Creating an passive channel will not cause an NCP connection
    attempt; this is done upon the first I/O request made to
    channel.

   BUGS
    None known.

   SEE ALSO
    NCP_CloseChannel()

ncp.library/NCP_Read                                     ncp.library/NCP_Read

   NAME
    NCP_Read -- do a read request.

   SYNOPSIS
    status = NCP_Read( channel, data, datasize )
      D0                     A0

    LONG NCP_Read( APTR, APTR, ULONG );

   FUNCTION
    This is basically identical to calling NCP_BeginRead()
    followed by NCP_WaitRead().

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()
    data -- receive buffer
    datasize -- receive buffer size

   RESULT
    status -- number of bytes read or a negative error
              number.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
    NCP_WaitRead(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()

ncp.library/NCP_ReadSig                               ncp.library/NCP_ReadSig

   NAME
    NCP_ReadSig -- return signal mask of channel read port.

   SYNOPSIS
    sigmask = NCP_ReadSig( channel )
      D0                     A0

    ULONG NCP_ReadSig( APTR );

   FUNCTION
    This function returns the signal mask of the read port
    of the given NCP channel. This signal is set if a read
    request completes.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    sigmask -- signal mask of read port.

   EXAMPLE

   NOTES
    Note that this function returns a signal mask, not a signal bit number.

   BUGS

   SEE ALSO
    NCP_BeginRead()

ncp.library/NCP_WaitRead                             ncp.library/NCP_WaitRead

   NAME
    NCP_WaitRead -- complete a read request on the NCP channel.

   SYNOPSIS
    result = NCP_WaitRead( channel )
      D0                     A0

    LONG NCP_WaitRead( APTR );

   FUNCTION
    Waits for the current read request to finish and
    returns the result.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    status -- number of bytes read or a negative error
              number.

   EXAMPLE

   NOTES
    Every read request startet with NCP_BeginRead() absolutely
    must be followed by a NCP_WaitRead(), even if it already
    finished or was aborted via NCP_AbortRead().

   BUGS
    Calling this function without an queued read request
    will hang up your process.

   SEE ALSO
    NCP_Read(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()

ncp.library/NCP_WaitWrite                           ncp.library/NCP_WaitWrite

   NAME
    NCP_WaitWrite -- complete a write request on the NCP channel.

   SYNOPSIS
    result = NCP_WaitWrite( channel )
      D0                     A0

    LONG NCP_WaitWrite( APTR );

   FUNCTION
    Waits for the current write request to finish and
    returns the result.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    status -- number of bytes written or a negative error
              number.

   EXAMPLE

   NOTES
    Every write request startet with NCP_BeginWrite() absolutely
    must be followed by a NCP_WaitWrite(), even if it already
    finished or was aborted via NCP_AbortWrite().

   BUGS
    Calling this function without an queued write request
    will hang up your process.

   SEE ALSO
    NCP_Write(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()

ncp.library/NCP_Write                                   ncp.library/NCP_Write

   NAME
    NCP_Write -- do a write request.

   SYNOPSIS
    status = NCP_Write( channel, data, datasize )
      D0                   A0     A1      D0

    LONG NCP_Write( APTR, APTR, ULONG );

   FUNCTION
    This is basically identical to calling NCP_BeginWrite()
    followed by NCP_WaitWrite().

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()
    data -- receive buffer
    datasize -- receive buffer size

   RESULT
    status -- number of bytes written or a negative error
              number.

   EXAMPLE

   NOTES

   BUGS

   SEE ALSO
    NCP_WaitWrite(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()

ncp.library/NCP_WriteSig                             ncp.library/NCP_WriteSig

   NAME
    NCP_WriteSig -- return signal mask of channel write port.

   SYNOPSIS
    sigmask = NCP_WriteSig( channel )
      D0                     A0

    ULONG NCP_WriteSig( APTR );

   FUNCTION
    This function returns the signal mask of the write port
    of the given NCP channel. This signal is set if a write
    request completes.

   INPUTS
    channel -- a NCP channel created by NCP_OpenChannel()

   RESULT
    sigmask -- signal mask of write port.

   EXAMPLE

   NOTES
    Note that this function returns a signal mask, not a signal bit number.

   BUGS

   SEE ALSO
    NCP_BeginWrite()