C Language Development Kit/Functions/NetO Receive

From OptiWiki

Jump to: navigation, search
Description This routine uses the NetO protocol to receive one or more complete files through the serial communications port that was last opened by comopen(). The NetO protocol is especially suited for a network environment. neto_receive2() can be given a time-out value.
Syntax 
int neto_receive( char (*filename)[MAX_FNAME], char *term_id, int tkey, int ypos );
int neto_receive2( char (*filename)[MAX_FNAME], char *term_id, unsigned int timeout, int tkey, int ypos );

Note: On the OPH 100x and H 13, MAX_FNAME should be defined as 16. On all other terminals, MAX_FNAME should be defined as 13.

Arguments 
char (*filename)[MAX_FNAME]
An array of strings, each string containing up to twelve characters plus the null character. Each string contains the name of the file that was received. Only when the reception was successful, does filename contain the valid names.

The number of strings in the array is equal to the return value of neto_receive(), if no reception error occurred. 

char *term_id
Points to a string containing the name (or: ID) of the terminal. The string can have a maximum of 6 characters. 
unsigned int timeout
timeout is the maximum time that may pass between calling the function and receiving a valid poll from the PC. Once a valid poll has been received, the protocol takes over and another time-out mechanism starts. The protocol specifies that when 3 seconds pass without receiving an answer from the PC a time-out error occurs.

timeout is set in steps of 20 ms, any value between 20 ms and 65535*20 ms. When you specify a time-out of 0, it means no time-out, i.e. infinite time. neto_receive2() with a timeout of 0, is identical to neto_receive(). 

int tkey
Value for the termination key. When the user presses this key the file reception will terminate. Specify a non-existing value, e.g. -1, when you do not want to give the user the option to terminate file reception. 
int ypos
The y position (in character coordinates) of the progress bar. Use -1 to not display the progress bar. The progress information consists of three lines. On the first line is the file name. On the second line is the 0% ... 100% indicator. On the third line is the actual progress bar marked as a string of ******. ypos specifies the line on which the ****** will appear. The file name therefore will appear on line ypos - 2.
Returns The number of files (positive value) received if all files were received OK, or an error code (negative value) specified as follows: ERROR Error after three retries.
ERR_USER_BREAK The user pressed the termination key.
ERR_TIME_OUT The specified timeout passed without receiving a poll.
ERR_EOT_HOST The host aborted transmission.
ERR_HOST_REQ Host and terminal request did not match.
ERR_OPEN_FILE Could not open file.
ERR_WRITE_FILE Could not write to file.
ERR_READ_FILE Could not read from file.
ERR_OUT_SYNC Serial number of blocks out of sync.
ERR_ALOC_MEM Could not allocate memory for RX/TX buffers.
Remarks When these functions draw the progress bar, they change the cursor settings to AUTOWRAP, See the cursor() function for details.

Important:

  • Except on the H 13 & OPH100x, the NetO protocol needs at least 4K of free memory for allocating input and output buffers.
  • Always use COM2 instead of COM1 when using the NetO protocol with the RS485 port of the cradle.
  • The H 13 and OPH100x terminals may add A: or C: to the filename to specify the location of the file (RAM disk resp. SD card), hence the longer buffer. Only the OPH 1003 actually does something with the drive name, the OPH 1004 and H 13 do accept the name, but it is simply ignored.
Example 
// To use the following example the user must have access to a NetO protocol
// upload and download utility on the host. The application first tries to receive
// up to two files, and next tries to transmit the same file(s) back.
//
// The ENT key can be used to terminate the file reception/transmission.
//
// The terminal is assigned the terminal ID "123456". The terminal ID can be used to
// distinguish the terminal from other terminals in a network.
 
#include <stdio.h>
#include "lib.h"
 
void main( void )
{
#ifdef OPH                        // OPH is defined when the code is build for the OPH1003! (So not the OPH1004)
    char ftest[10][16];           // Array for ten filenames; static not required for OPH1003
#else
    static char ftest[10][13];    // Array for ten filenames; static so space is not on stack
#endif
    int test;
 
    systemsetting("K7");          // 19200bps (N, 8, 1)
 
    for(;;)
    {
        if( comopen( COM2 ) != OK)      // COM2 is the cradle
        {
            printf("\fCan't open port");
 
            resetkey();
            while( !kbhit())
                idle();
 
            continue;
        }
 
        do
        {
            printf("\fReceiving..");
            test = neto_receive( ftest, "123456", ENT_KEY, 3);
            printf("\ntest=%d", test);
        } while( test < 0);
 
        comclose( COM2 );    // Saves power
 
        printf("\fresult = %d", test);
        printf("\npress any key");
 
        resetkey();
        while( !kbhit())
            idle();
 
        if( comopen( COM2 ) != OK)
        {
            resetkey();
            while( !kbhit())
                idle();
 
            continue;
        }
 
        printf("\fTransmitting...\n%d files", test);
        test = neto_transmit( ftest, test, "123456", ENT_KEY, 3);
 
        printf("\fresult = %d", test);
        printf("\npress any key");
 
        comclose( COM2 );
 
        resetkey();
        while( !kbhit())
            idle();
    }
}


Retrieved from "http://wiki.opticon.com/index.php/C_Language_Development_Kit/Functions/NetO_Receive"
Views
Personal tools