CTCLChannel

DESCRIPTION

The Tcl API supplies an I/O abstraction layer on top of the operating systems I/O subsystem. This layer makes use of what Tcl documentation refers to a s channels. A channel represents a connection to an I/O endpoint (source or sink of data or both). The CTCLChannel class allows you to wrap a C++ class around a Tcl channel.

Using a CTCLChannel, rather than direct operating system I/O allows you to improve the portability of your program, as well as allowing I/O from the TCL scripting level to be cleanly mixed with I/O at the C/C++ level.

METHODS

  CTCLChannel(CTCLInterpreter* pInterp,
              std::string      Filename,
              const char*      pMode,
              int              permissions);
  CTCLChannel(CTCLInterpreter* pInterp,
              int              argc,
              const char**           pargv,
              int              flags);
  CTCLChannel(CTCLInterpreter  * pInterp,
              int              port,
              std::string      host);
  CTCLChannel(CTCLInterpreter* pInterp,
              int              port,
              Tcl_TcpAcceptProc* proc,
              ClientData      AppData);
  CTCLChannel(CTCLInterpreter* pInterp,
              Tcl_Channel      Channel);
  CTCLChannel(const CTCLChannel& rhs);
        

These constructors wrap a CTCLChannel object around a Tcl channel. The variety of constructors reflects the variety of endpoints around which a Tcl_Channel can be wrapped.

The first of the constructors attaches the object to a file via Tcl_OpenFileChannel. pInterp is the channel the file is associated. Filename is the name of the file the channel is connected to. pMode is the connection mode which can be any of of the mode values for the Tcl open scripting command. permissions represents the permissions mask fo rthe file in POSIX format. See open(2) for information about the possible mode bit values.

The second form of the constructor connects a channel that is a pipe to a program. The program and its command line arguments are specified via the argc and pargv parameters. The flags parameter specifies how the stdio channels of the program are or are not disposed into the channel. Valid bits are: TCL_STDIN, TCL_STDOUT, TCL_STDERR, TCL_ENFORCE_MODE. See the Tcl_OpenCommandChannel manpage for information about the meaning of these bits.

The third form of the constructor constructs a channel that connects to a TCP/IP server, via Tcl_OpenTcpClient. The port parameter specifies the port number on which the server is listening, while host is the name of the host to which the connection should be formed. The host name can either be a DNS resolvable host name or the textual encoding of the TCP/IP address of the host (e.g. string("spdaq22.nscl.msu.edu") or string("35.9.56.56"). This function will block until the connection is accepted by the server.

The fourth form of the constructor creates a channel that is a Tcp/IP server. port is the port number on which the server listens for connections. proc is a function that will be called when a connection has been accepted by the Tcl event loop. AppData is application data that is passed, without interpretation to proc. See the Tcl_OpenTcpServer manpage for more information about how the proc is called.

The fifth form of the constructor creates a CTCLChannel object by wrapping an existing Tcl_Channel; Channel which has been obtained directly from the Tcl application programming interface.

The final form of the constructor copies an existing CTCLChannel object so that the two objects refer to the same channel. The object is created so that it will not close the channel on destruction. Note however that the source channel may, depending on how it was constructed. It is up to the application programmer to ensure that channels are closed at appropriate times.

  Tcl_Channel getChannel() const;
        

Returns the underlying Tcl_Channel this object is wrapped around. Once this is obtained, it can be usd in any Tcl API call that requires a channel.

  bool ClosesOnDestroy() const;
        

When a CTCLChannel is copy constructed into being it is flagged such that destruction will not close the underlying channel. the return value from this function is true if the object will close the underlying channel on destruction and false if the object will not close the underlying channel on destruction.

  int Read( void** pData,
           int nChars);
  int Write(const void* pData,
           int nBytes);
        

Read transfers data from the channel to the users's buffer; pData. nChars is the number of characters of data that will be transferred. Write transfers nBytes bytes data to the chnnel from pData. Both function return the number of characters actually transferred. An important note about the nChars parameter: If the channel is not opened as a binary channel, this parameter is the number of UTF-8 characters transferred. Depending on the characters actually transmitted, this may not be the same as the number of bytes transmitted. The return value is the number of units (bytes or characters) actually transferred.

  bool atEof();
        

Returns true if the underlying channel is at the end of file.

  void Flush();
        

Tcl channels are internally buffered. The Flush member flushes internal output buffers to the underlying I/O endpoint.

  void Close();
        

Closes the underlying channel. Note that this is normally done on destruction unless the channel object was created via copy construction. If the channel was registered to be visible to the interpreter, it is unregistered as well.

  void Register();
        

Makes the channel visible to the interpreter. This allows the user to return the channel name to the script level at which point it can be used in Tcl script commands that operate on channels.

  void SetEncoding(std::string Name);
  std::string GetEncoding();
        

These functions allow the user to get and set the encoding for the channel. See the fconfigure Tcl man page for more information about this.

SEE ALSO

close(3tcl), fconfigure(3tcl), open(2), Tcl_OpenCommandChannel(3tcl), Tcl_OpenFileChannel(3tcl), Tcl_OpenTcpClient(3tcl), Tcl_OpenTcpServer(3tcl)