通讯编程

开发平台：
Visual C++

CrtCommand.3：源码内容
							'"
'" Copyright (c) 1989-1993 The Regents of the University of California.
'" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: CrtCommand.3,v 1.5.2.1 2004/07/16 20:46:52 andreas_kupries Exp $
'" 
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateCommand - implement new commands in C
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
Tcl_Command
fBTcl_CreateCommandfR(fIinterp, cmdName, proc, clientData, deleteProcfR)
.SH ARGUMENTS
.AS Tcl_CmdDeleteProc **deleteProcPtr
.AP Tcl_Interp *interp in
Interpreter in which to create new command.
.VS 8.4
.AP "CONST char" *cmdName in
.VE
Name of command.
.AP Tcl_CmdProc *proc in
Implementation of new command:  fIprocfR will be called whenever
fIcmdNamefR is invoked as a command.
.AP ClientData clientData in
Arbitrary one-word value to pass to fIprocfR and fIdeleteProcfR.
.AP Tcl_CmdDeleteProc *deleteProc in
Procedure to call before fIcmdNamefR is deleted from the interpreter;
allows for command-specific cleanup.  If NULL, then no procedure is
called before the command is deleted.
.BE
.SH DESCRIPTION
.PP
fBTcl_CreateCommandfR defines a new command in fIinterpfR and associates
it with procedure fIprocfR such that whenever fIcmdNamefR is
invoked as a Tcl command (via a call to fBTcl_EvalfR) the Tcl interpreter
will call fIprocfR to process the command.
It differs from fBTcl_CreateObjCommandfR in that a new string-based
command is defined;
that is, a command procedure is defined that takes an array of
argument strings instead of objects.
The object-based command procedures registered by fBTcl_CreateObjCommandfR
can execute significantly faster than the string-based command procedures
defined by fBTcl_CreateCommandfR.
This is because they take Tcl objects as arguments
and those objects can retain an internal representation that
can be manipulated more efficiently.
Also, Tcl's interpreter now uses objects internally.
In order to invoke a string-based command procedure
registered by fBTcl_CreateCommandfR,
it must generate and fetch a string representation
from each argument object before the call
and create a new Tcl object to hold the string result returned by the
string-based command procedure.
New commands should be defined using fBTcl_CreateObjCommandfR.
We support fBTcl_CreateCommandfR for backwards compatibility.
.PP
The procedures fBTcl_DeleteCommandfR, fBTcl_GetCommandInfofR,
and fBTcl_SetCommandInfofR are used in conjunction with
fBTcl_CreateCommandfR.
.PP
fBTcl_CreateCommandfR will delete an existing command fIcmdNamefR,
if one is already associated with the interpreter.
It returns a token that may be used to refer
to the command in subsequent calls to fBTcl_GetCommandNamefR.
If fIcmdNamefR contains any fB::fR namespace qualifiers,
then the command is added to the specified namespace;
otherwise the command is added to the global namespace.
If fBTcl_CreateCommandfR is called for an interpreter that is in
the process of being deleted, then it does not create a new command
and it returns NULL.
fIProcfR should have arguments and result that match the type
fBTcl_CmdProcfR:
.CS
typedef int Tcl_CmdProc(
	ClientData fIclientDatafR,
	Tcl_Interp *fIinterpfR,
	int fIargcfR,
	CONST char *fIargvfR[]);
.CE
When fIprocfR is invoked the fIclientDatafR and fIinterpfR
parameters will be copies of the fIclientDatafR and fIinterpfR
arguments given to fBTcl_CreateCommandfR.
Typically, fIclientDatafR points to an application-specific
data structure that describes what to do when the command procedure
is invoked.  fIArgcfR and fIargvfR describe the arguments to
the command, fIargcfR giving the number of arguments (including
the command name) and fIargvfR giving the values of the arguments
as strings.  The fIargvfR array will contain fIargcfR+1 values;
the first fIargcfR values point to the argument strings, and the
last value is NULL.  
.VS
Note that the argument strings should not be modified as they may
point to constant strings or may be shared with other parts of the
interpreter.
.VE
.PP
.VS
Note that the argument strings are encoded in normalized UTF-8 since
version 8.1 of Tcl.
.VE
.PP
fIProcfR must return an integer code that is either fBTCL_OKfR, fBTCL_ERRORfR,
fBTCL_RETURNfR, fBTCL_BREAKfR, or fBTCL_CONTINUEfR.  See the Tcl overview man page
for details on what these codes mean.  Most normal commands will only
return fBTCL_OKfR or fBTCL_ERRORfR.  In addition, fIprocfR must set
the interpreter result to point to a string value;
in the case of a fBTCL_OKfR return code this gives the result
of the command, and in the case of fBTCL_ERRORfR it gives an error message.
The fBTcl_SetResultfR procedure provides an easy interface for setting
the return value;  for complete details on how the the interpreter result
field is managed, see the fBTcl_InterpfR man page.
Before invoking a command procedure,
fBTcl_EvalfR sets the interpreter result to point to an empty string,
so simple commands can return an empty result by doing nothing at all.
.PP
The contents of the fIargvfR array belong to Tcl and are not
guaranteed to persist once fIprocfR returns:  fIprocfR should
not modify them, nor should it set the interpreter result to point
anywhere within the fIargvfR values.
Call fBTcl_SetResultfR with status fBTCL_VOLATILEfR if you want
to return something from the fIargvfR array.
.PP
fIDeleteProcfR will be invoked when (if) fIcmdNamefR is deleted.
This can occur through a call to fBTcl_DeleteCommandfR or fBTcl_DeleteInterpfR,
or by replacing fIcmdNamefR in another call to fBTcl_CreateCommandfR.
fIDeleteProcfR is invoked before the command is deleted, and gives the
application an opportunity to release any structures associated
with the command.  fIDeleteProcfR should have arguments and
result that match the type fBTcl_CmdDeleteProcfR:
.CS
typedef void Tcl_CmdDeleteProc(ClientData fIclientDatafR);
.CE
The fIclientDatafR argument will be the same as the fIclientDatafR
argument passed to fBTcl_CreateCommandfR.
.PP
.SH "SEE ALSO"
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
.SH KEYWORDS
bind, command, create, delete, interpreter, namespace

						