home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / sqlnet / net23 / client / tnsapi.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-12-27  |  7.1 KB  |  281 lines
  1. /*
  2.   $Header: /netrcs/RCS/oracle/network/tns/defs/RCS/tnsapi.h,v 1.4 1995/09/12 19:35:07 yzheng Exp $
  3. */
  4.  
  5. /* Copyright (c) 1995 by Oracle Corporation.  All rights reserved. */
  6.  
  7. /*
  8.  
  9. NAME
  10.   tnsapi.h
  11.  
  12. DESCRIPTION
  13.   SQL*Net Open API functions.
  14.  
  15. FUNCTIONS
  16.   tnsopen()    -   open a TNS handle
  17.   tnsclose()   -   close a TNS handle
  18.   tnssend()    -   send data over TNS handle
  19.   tnsrecv()    -   receive data over TNS handle
  20.  
  21. NOTES
  22.   These functions provides transparent access to the underlying session 
  23.   implementation SQL*NET.
  24.  
  25. */
  26.  
  27. #ifndef TNSAPI
  28. #define TNSAPI
  29.  
  30. enum tnsapiopcode {
  31. /* TNS API operations */
  32.   TNSAPIOOPEN,                
  33.   TNSAPIOCLOSE,               
  34.   TNSAPIOSEND,                
  35.   TNSAPIORECV
  36. };
  37.  
  38. /* TNS API error codes */
  39. /* More will be added as actual coding and testing starts */
  40. /* DISABLE check_naming */
  41. /* DISABLE check_str_mem */
  42. enum tnsapierrcode {
  43.   TNSAPIEBASE = 20000,
  44.  
  45.   SDFAIL_TNSAPIE = TNSAPIEBASE+2,
  46. /*
  47.  * SDFAIL_TNSAPIE: The underlying "send" command failed in tnssend().
  48.  */
  49.  
  50.   RECVFAIL_TNSAPIE = TNSAPIEBASE+3,
  51. /*
  52.  * RECVFAIL_TNSAPIE: The underlying "receive" command failed in tnsrecv().
  53.  */
  54.  
  55.   INVSVROP_TNSAPIE = TNSAPIEBASE+4,
  56. /*
  57.  * INVSVROP_TNSAPIE: Operation is invalid as the server.
  58.  */
  59.  
  60.   INVCLIOP_TNSAPIE = TNSAPIEBASE+5,
  61. /*
  62.  * INVCLIOP_TNSAPIE: Operation is invalid as the client.
  63.  */
  64.  
  65.   HDLUNINI_TNSAPIE = TNSAPIEBASE+6,
  66. /*
  67.  * HDLUNINI_TNSAPIE: The connection should be initialized by 
  68.  * calling tnsopen(). 
  69.  */
  70.  
  71.   INHFAIL_TNSAPIE = TNSAPIEBASE+7,
  72. /*
  73.  * INHFAIL_TNSAPIE: server failed in inheriting the connection from
  74.  * the listener.
  75.  */
  76.  
  77.   ACPTFAIL_TNSAPIE = TNSAPIEBASE+8,
  78. /*
  79.  * ACPTFAIL_TNSAPIE: server failed in accepting the connection request
  80.  * from the client
  81.  */
  82.  
  83.   NULHDL_TNSAPIE = TNSAPIEBASE+9,
  84. /*
  85.  * NULHDL_TNSAPIE: a null handle is passed into the tnsxxx calls, which
  86.  * is not allowed
  87.  */
  88.  
  89.   INVOP_TNSAPIE = TNSAPIEBASE+10,
  90. /*
  91.  * INVOP_TNSAPIE: invalid operation code is passed into tnsapi() call
  92.  */
  93.  
  94.   MALFAIL_TNSAPIE = TNSAPIEBASE+11,
  95. /*
  96.  * MALFAIL_TNSAPIE: a malloc failed in TNS API calls
  97.  */
  98.  
  99.   NLINIFAIL_TNSAPIE = TNSAPIEBASE+12,
  100. /*
  101.  * NLINIFAIL_TNSAPIE: failed in NL initialization 
  102.  */
  103.  
  104.   NMTOOLONG_TNSAPIE = TNSAPIEBASE+13,
  105. /*
  106.  * NMTOOLONG_TNSAPIE: service name too long
  107.  */
  108.  
  109.   CONFAIL_TNSAPIE = TNSAPIEBASE+14,
  110. /*
  111.  * CONFAIL_TNSAPIE: client connect request failed
  112.  */
  113.  
  114.   LSNFAIL_TNSAPIE = TNSAPIEBASE+15,
  115. /*
  116.  * LSNFAIL_TNSAPIE: server failed to listen for connect request
  117.  */
  118.  
  119.   ANSFAIL_TNSAPIE = TNSAPIEBASE+16,
  120. /*
  121.  * ANSFAIL_TNSAPIE: server failed to answer connect request
  122.  */
  123.  
  124.   NMRESFAIL_TNSAPIE = TNSAPIEBASE+17,
  125. /*
  126.  * NMRESFAIL_TNSAPIE: failed to resolve service name
  127.  */
  128.  
  129.   TNSAPIE_ERROR = TNSAPIEBASE+20
  130. /*
  131.  * TNSAPIE_ERROR: generic TNS error occured
  132.  */
  133.  
  134. };
  135. /* ENABLE check_str_mem */
  136.  
  137. int tnsopen(/*_ void **handlep, const char *name _*/);
  138. /*
  139.  * Operation
  140.  *   TNSOPEN
  141.  *
  142.  * Description
  143.  *   Initialize TNSAPI per-connection handle. This function must be the
  144.  *   first TNS call that a user makes.
  145.  *
  146.  *   Name contains a service name in the same format as those in 
  147.  *   configuration files in the case of a client. In the case of a server,
  148.  *   name is a NULL.
  149.  *
  150.  * Synopsis
  151.  *   int tnsopen(handlep, name)
  152.  *   void **handlep;
  153.  *   const char *name;
  154.  *
  155.  * Paramters
  156.  *   handlep (IN/OUT) - Address to receive TNS connection handle
  157.  *   name    (IN)     - service name
  158.  *      
  159.  * Requires
  160.  *   The handlep paramter must not be NULL
  161.  *
  162.  * Returns
  163.  *   Upon successful completion a zero value is returned. Otherwise, a
  164.  *   positive TNS API error is returned, which is defined in this header 
  165.  *   file. 
  166.  */
  167.  
  168. int tnsclose(/*_ void **handlep _*/);
  169. /*
  170.  * Operation:
  171.  *  TNSCLOSE
  172.  *
  173.  * Description
  174.  *  Shut down the connection. This function must be called by the user
  175.  *  to close the connection and release the handle properly.
  176.  *
  177.  * Synopsis
  178.  *   int tnsclose(handlep)
  179.  *   void **handlep;
  180.  *
  181.  * Paramters
  182.  *   handlep(IN/OUT) - Address of a pointer to a TNS connection handle    
  183.  * 
  184.  * Requires
  185.  *   The handlep paramter must not be NULL
  186.  *  
  187.  * Returns
  188.  *   Upon successful completion a zero value is returned, and *handlep
  189.  *   is set to NULL. Otherwise, a positive TNS API error number  is 
  190.  *   returned, which is defined in this header file. 
  191.  */
  192.  
  193.  
  194. int tnssend(/*_ void *handle, const void *data, size_t *length _*/);
  195. /*
  196.  * Operation
  197.  *   TNSSEND
  198.  *
  199.  * Description
  200.  *   Send data to the TNS handle.
  201.  *
  202.  *   In the first call to tnssend() on the client side, connection is
  203.  *   first established before data is sent to the handle.  The client must 
  204.  *   first call tnssend() after tnsopen() to establish a connection to the 
  205.  *   server. It is an error if server calls tnssend() after calling 
  206.  *   tnsopen().
  207.  *
  208.  * Synopsis
  209.  *   int tnssend(handle, data, length)
  210.  *   void *handle;
  211.  *   const void *data;
  212.  *   size_t *length;
  213.  *
  214.  * Paramters
  215.  *   handle(IN/OUT) - pointer to TNS connection handle returned by 
  216.  *                    tnsopen() 
  217.  *   data(IN)   -     pointer to data to be sent
  218.  *   length(IN/OUT) - pointer to the length of data to be sent in bytes
  219.  *                    and the actual number of bytes written on return.
  220.  *
  221.  * Requires
  222.  *   The paramters must not be NULL
  223.  * 
  224.  * Returns
  225.  *   Upon successful completion a zero value is returned, and the actual 
  226.  *   number of bytes written is returned as the value pointed to by the
  227.  *   length paramter. Otherwise, a positive TNS API error number is 
  228.  *   returned, which is defined in this header file. 
  229.  */
  230.  
  231.  
  232. int tnsrecv(/*_ void *handle, void *data, size_t *length _*/);
  233. /*
  234.  * Operation
  235.  *   TNSRECV
  236.  *
  237.  * Description
  238.  *   Receive data from the TNS handle
  239.  *  
  240.  *   In the frist call to tnsrecv() on the server side, connection is 
  241.  *   first established before data is received from the handle. The server
  242.  *   must first call tnsrecv() after tnsopen() to accept the connection
  243.  *   from the client. 
  244.  *
  245.  * Synopsis
  246.  *   int tnsrecv(handle, data, length)
  247.  *   void *handle;
  248.  *   void *data;
  249.  *   size_t *length;
  250.  *
  251.  * Paramters
  252.  *   handle(IN/OUT) - pointer to TNS connection handle returned by 
  253.  *                    tnsopen()
  254.  *   data(IN/OUT)   - pointer to buffer to receive data
  255.  *   length(IN/OUT) - pointer to the length of buffer to receive data
  256.  *                    and actual number of bytes received on return
  257.  *
  258.  * Requires
  259.  *   All paramters must not be NULL
  260.  *  
  261.  * Returns
  262.  *   Upon successful completion a zero value is returned, and the actual 
  263.  *   number of bytes received is returned as the value pointed to by the
  264.  *   length paramter. Otherwise, a positive TNS API error number is 
  265.  *   returned, which is defined in this header file.
  266.  */
  267.  
  268.   
  269.  
  270. /*
  271.  * Public macro interfaces 
  272.  */
  273. #define tnsopen(handlep, name) tnsapi(TNSAPIOOPEN, handlep, name)
  274. #define tnsclose(handlep) tnsapi(TNSAPIOCLOSE, handlep)
  275. #define tnssend(handle, data, length) tnsapi(TNSAPIOSEND, handle, data, length)
  276. #define tnsrecv(handle, data, length) tnsapi(TNSAPIORECV, handle, data, length)
  277.  
  278. /* ENABLE check_naming */
  279.  
  280. #endif /* TNSAPI */
  281.