CrtObjCmd.3
上传用户:rrhhcc
上传日期:2015-12-11
资源大小:54129k
文件大小:13k
源码类别:

通讯编程

开发平台:

Visual C++

  1. '"
  2. '" Copyright (c) 1996-1997 Sun Microsystems, Inc.
  3. '"
  4. '" See the file "license.terms" for information on usage and redistribution
  5. '" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  6. '" 
  7. '" RCS: @(#) $Id: CrtObjCmd.3,v 1.7.2.1 2004/05/05 20:54:47 dkf Exp $
  8. '" 
  9. .so man.macros
  10. .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
  11. .BS
  12. .SH NAME
  13. Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj - implement new commands in C
  14. .SH SYNOPSIS
  15. .nf
  16. fB#include <tcl.h>fR
  17. .sp
  18. Tcl_Command
  19. fBTcl_CreateObjCommandfR(fIinterp, cmdName, proc, clientData, deleteProcfR)
  20. .sp
  21. int
  22. fBTcl_DeleteCommandfR(fIinterp, cmdNamefR)
  23. .sp
  24. int
  25. fBTcl_DeleteCommandFromTokenfR(fIinterp, tokenfR)
  26. .sp
  27. int
  28. fBTcl_GetCommandInfofR(fIinterp, cmdName, infoPtrfR)
  29. .sp
  30. int
  31. fBTcl_SetCommandInfofR(fIinterp, cmdName, infoPtrfR)
  32. .sp
  33. .VS 8.4
  34. int
  35. fBTcl_GetCommandInfoFromTokenfR(fItoken, infoPtrfR)
  36. .sp
  37. int
  38. fBTcl_SetCommandInfoFromTokenfR(fItoken, infoPtrfR)
  39. .VE
  40. .sp
  41. .VS 8.4
  42. CONST char *
  43. .VE
  44. fBTcl_GetCommandNamefR(fIinterp, tokenfR)
  45. .sp
  46. void
  47. fBTcl_GetCommandFullNamefR(fIinterp, token, objPtrfR)
  48. .sp
  49. Tcl_Command
  50. fBTcl_GetCommandFromObjfR(fIinterp, objPtrfR)
  51. .SH ARGUMENTS
  52. .AS Tcl_ObjCmdProc *deleteProc in/out
  53. .AP Tcl_Interp *interp in
  54. Interpreter in which to create a new command or that contains a command.
  55. .VS 8.4
  56. .AP char *cmdName in
  57. .VE
  58. Name of command.
  59. .AP Tcl_ObjCmdProc *proc in
  60. Implementation of the new command: fIprocfR will be called whenever
  61. fIcmdNamefR is invoked as a command.
  62. .AP ClientData clientData in
  63. Arbitrary one-word value to pass to fIprocfR and fIdeleteProcfR.
  64. .AP Tcl_CmdDeleteProc *deleteProc in
  65. Procedure to call before fIcmdNamefR is deleted from the interpreter;
  66. allows for command-specific cleanup. If NULL, then no procedure is
  67. called before the command is deleted.
  68. .AP Tcl_Command token in
  69. Token for command, returned by previous call to fBTcl_CreateObjCommandfR.
  70. The command must not have been deleted.
  71. .AP Tcl_CmdInfo *infoPtr in/out
  72. Pointer to structure containing various information about a
  73. Tcl command.
  74. .AP Tcl_Obj *objPtr in
  75. Object containing the name of a Tcl command.
  76. .BE
  77. .SH DESCRIPTION
  78. .PP
  79. fBTcl_CreateObjCommandfR defines a new command in fIinterpfR
  80. and associates it with procedure fIprocfR
  81. such that whenever fInamefR is
  82. invoked as a Tcl command (e.g., via a call to fBTcl_EvalObjExfR)
  83. the Tcl interpreter will call fIprocfR to process the command.
  84. .PP
  85. fBTcl_CreateObjCommandfR deletes any existing command
  86. fInamefR already associated with the interpreter
  87. (however see below for an exception where the existing command
  88. is not deleted).
  89. It returns a token that may be used to refer
  90. to the command in subsequent calls to fBTcl_GetCommandNamefR.
  91. If fInamefR contains any fB::fR namespace qualifiers,
  92. then the command is added to the specified namespace;
  93. otherwise the command is added to the global namespace.
  94. If fBTcl_CreateObjCommandfR is called for an interpreter that is in
  95. the process of being deleted, then it does not create a new command
  96. and it returns NULL.
  97. fIprocfR should have arguments and result that match the type
  98. fBTcl_ObjCmdProcfR:
  99. .CS
  100. typedef int Tcl_ObjCmdProc(
  101. ClientData fIclientDatafR,
  102. Tcl_Interp *fIinterpfR,
  103. int fIobjcfR,
  104. .VS
  105. Tcl_Obj *CONST fIobjvfR[]);
  106. .CE
  107. When fIprocfR is invoked, the fIclientDatafR and fIinterpfR parameters
  108. will be copies of the fIclientDatafR and fIinterpfR arguments given to
  109. fBTcl_CreateObjCommandfR.  Typically, fIclientDatafR points to an
  110. application-specific data structure that describes what to do when the
  111. command procedure is invoked. fIObjcfR and fIobjvfR describe the
  112. arguments to the command, fIobjcfR giving the number of argument objects
  113. (including the command name) and fIobjvfR giving the values of the
  114. arguments.  The fIobjvfR array will contain fIobjcfR values, pointing to
  115. the argument objects.  Unlike fIargvfR[fIargvfR] used in a
  116. string-based command procedure, fIobjvfR[fIobjcfR] will not contain NULL.
  117. .PP
  118. Additionally, when fIprocfR is invoked, it must not modify the contents
  119. of the fIobjvfR array by assigning new pointer values to any element of the
  120. array (for example, fIobjvfR[fB2fR] = fBNULLfR) because this will
  121. cause memory to be lost and the runtime stack to be corrupted.  The
  122. fBCONSTfR in the declaration of fIobjvfR will cause ANSI-compliant
  123. compilers to report any such attempted assignment as an error.  However,
  124. it is acceptable to modify the internal representation of any individual
  125. object argument.  For instance, the user may call
  126. fBTcl_GetIntFromObjfR on fIobjvfR[fB2fR] to obtain the integer
  127. representation of that object; that call may change the type of the object
  128. that fIobjvfR[fB2fR] points at, but will not change where
  129. fIobjvfR[fB2fR] points.
  130. .VE
  131. .PP
  132. fIprocfR must return an integer code that is either fBTCL_OKfR,
  133. fBTCL_ERRORfR, fBTCL_RETURNfR, fBTCL_BREAKfR, or fBTCL_CONTINUEfR.
  134. See the Tcl overview man page
  135. for details on what these codes mean.  Most normal commands will only
  136. return fBTCL_OKfR or fBTCL_ERRORfR.
  137. In addition, if fIprocfR needs to return a non-empty result,
  138. it can call fBTcl_SetObjResultfR to set the interpreter's result.
  139. In the case of a fBTCL_OKfR return code this gives the result
  140. of the command,
  141. and in the case of fBTCL_ERRORfR this gives an error message.
  142. Before invoking a command procedure,
  143. fBTcl_EvalObjExfR sets interpreter's result to
  144. point to an object representing an empty string, so simple
  145. commands can return an empty result by doing nothing at all.
  146. .PP
  147. The contents of the fIobjvfR array belong to Tcl and are not
  148. guaranteed to persist once fIprocfR returns: fIprocfR should
  149. not modify them.
  150. Call fBTcl_SetObjResultfR if you want
  151. to return something from the fIobjvfR array.
  152. .PP
  153. Ordinarily, fBTcl_CreateObjCommandfR deletes any existing command
  154. fInamefR already associated with the interpreter.
  155. However, if the existing command was created by a previous call to
  156. fBTcl_CreateCommandfR,
  157. fBTcl_CreateObjCommandfR does not delete the command
  158. but instead arranges for the Tcl interpreter to call the
  159. fBTcl_ObjCmdProcfR fIprocfR in the future.
  160. The old string-based fBTcl_CmdProcfR associated with the command
  161. is retained and its address can be obtained by subsequent 
  162. fBTcl_GetCommandInfofR calls. This is done for backwards compatibility.
  163. .PP
  164. fIDeleteProcfR will be invoked when (if) fInamefR is deleted.
  165. This can occur through a call to fBTcl_DeleteCommandfR,
  166. fBTcl_DeleteCommandFromTokenfR, or fBTcl_DeleteInterpfR,
  167. or by replacing fInamefR in another call to fBTcl_CreateObjCommandfR.
  168. fIDeleteProcfR is invoked before the command is deleted, and gives the
  169. application an opportunity to release any structures associated
  170. with the command.  fIDeleteProcfR should have arguments and
  171. result that match the type fBTcl_CmdDeleteProcfR:
  172. .CS
  173. typedef void Tcl_CmdDeleteProc(ClientData fIclientDatafR);
  174. .CE
  175. The fIclientDatafR argument will be the same as the fIclientDatafR
  176. argument passed to fBTcl_CreateObjCommandfR.
  177. .PP
  178. fBTcl_DeleteCommandfR deletes a command from a command interpreter.
  179. Once the call completes, attempts to invoke fIcmdNamefR in
  180. fIinterpfR will result in errors.
  181. If fIcmdNamefR isn't bound as a command in fIinterpfR then
  182. fBTcl_DeleteCommandfR does nothing and returns -1;  otherwise
  183. it returns 0.
  184. There are no restrictions on fIcmdNamefR:  it may refer to
  185. a built-in command, an application-specific command, or a Tcl procedure.
  186. If fInamefR contains any fB::fR namespace qualifiers,
  187. the command is deleted from the specified namespace.
  188. .PP
  189. Given a token returned by fBTcl_CreateObjCommandfR,
  190. fBTcl_DeleteCommandFromTokenfR deletes the command
  191. from a command interpreter.
  192. It will delete a command even if that command has been renamed.
  193. Once the call completes, attempts to invoke the command in
  194. fIinterpfR will result in errors.
  195. If the command corresponding to fItokenfR
  196. has already been deleted from fIinterpfR then
  197. fBTcl_DeleteCommandfR does nothing and returns -1;
  198. otherwise it returns 0.
  199. .PP
  200. fBTcl_GetCommandInfofR checks to see whether its fIcmdNamefR argument
  201. exists as a command in fIinterpfR.
  202. fIcmdNamefR may include fB::fR namespace qualifiers
  203. to identify a command in a particular namespace.
  204. If the command is not found, then it returns 0.
  205. Otherwise it places information about the command
  206. in the fBTcl_CmdInfofR structure
  207. pointed to by fIinfoPtrfR and returns 1.
  208. A fBTcl_CmdInfofR structure has the following fields:
  209. .CS
  210. typedef struct Tcl_CmdInfo {
  211.     int isNativeObjectProc;
  212.     Tcl_ObjCmdProc *objProc;
  213.     ClientData objClientData;
  214.     Tcl_CmdProc *proc;
  215.     ClientData clientData;
  216.     Tcl_CmdDeleteProc *deleteProc;
  217.     ClientData deleteData;
  218.     Tcl_Namespace *namespacePtr;
  219. } Tcl_CmdInfo;
  220. .CE
  221. The fIisNativeObjectProcfR field has the value 1
  222. if fBTcl_CreateObjCommandfR was called to register the command;
  223. it is 0 if only fBTcl_CreateCommandfR was called.
  224. It allows a program to determine whether it is faster to
  225. call fIobjProcfR or fIprocfR:
  226. fIobjProcfR is normally faster
  227. if fIisNativeObjectProcfR has the value 1.
  228. The fields fIobjProcfR and fIobjClientDatafR
  229. have the same meaning as the fIprocfR and fIclientDatafR
  230. arguments to fBTcl_CreateObjCommandfR;
  231. they hold information about the object-based command procedure
  232. that the Tcl interpreter calls to implement the command.
  233. The fields fIprocfR and fIclientDatafR
  234. hold information about the string-based command procedure
  235. that implements the command.
  236. If fBTcl_CreateCommandfR was called for this command,
  237. this is the procedure passed to it;
  238. otherwise, this is a compatibility procedure
  239. registered by fBTcl_CreateObjCommandfR
  240. that simply calls the command's
  241. object-based procedure after converting its string arguments to Tcl objects.
  242. The field fIdeleteDatafR is the ClientData value
  243. to pass to fIdeleteProcfR;  it is normally the same as
  244. fIclientDatafR but may be set independently using the
  245. fBTcl_SetCommandInfofR procedure.
  246. The field fInamespacePtrfR holds a pointer to the
  247. Tcl_Namespace that contains the command.
  248. .PP
  249. fBTcl_GetCommandInfoFromTokenfR is identical to
  250. fBTcl_GetCommandInfofR except that it uses a command token returned
  251. from fBTcl_CreateObjCommandfR in place of the command name.  If the
  252. fItokenfR parameter is NULL, it returns 0; otherwise, it returns 1
  253. and fills in the structure designated by fIinfoPtrfR.
  254. .PP
  255. fBTcl_SetCommandInfofR is used to modify the procedures and
  256. ClientData values associated with a command.
  257. Its fIcmdNamefR argument is the name of a command in fIinterpfR.
  258. fIcmdNamefR may include fB::fR namespace qualifiers
  259. to identify a command in a particular namespace.
  260. If this command does not exist then fBTcl_SetCommandInfofR returns 0.
  261. Otherwise, it copies the information from fI*infoPtrfR to
  262. Tcl's internal structure for the command and returns 1.
  263. .PP
  264. fBTcl_SetCommandInfoFromTokenfR is identical to
  265. fBTcl_SetCommandInfofR except that it takes a command token as
  266. returned by fBTcl_CreateObjCommandfR instead of the command name.
  267. If the fItokenfR parameter is NULL, it returns 0.  Otherwise, it
  268. copies the information from fI*infoPtrfR to Tcl's internal structure
  269. for the command and returns 1.
  270. .PP
  271. Note that fBTcl_SetCommandInfofR and
  272. fBTcl_SetCommandInfoFromTokenfR both allow the ClientData for a
  273. command's deletion procedure to be given a different value than the
  274. ClientData for its command procedure.
  275. .PP
  276. Note that neither fBTcl_SetCommandInfofR nor
  277. fBTcl_SetCommandInfoFromTokenfR will change a command's namespace.
  278. Use fBTcl_EvalfR to call the fBrenamefR command to do that.
  279. .PP
  280. fBTcl_GetCommandNamefR provides a mechanism for tracking commands
  281. that have been renamed.
  282. Given a token returned by fBTcl_CreateObjCommandfR
  283. when the command was created, fBTcl_GetCommandNamefR returns the
  284. string name of the command.  If the command has been renamed since it
  285. was created, then fBTcl_GetCommandNamefR returns the current name.
  286. This name does not include any fB::fR namespace qualifiers.
  287. The command corresponding to fItokenfR must not have been deleted.
  288. The string returned by fBTcl_GetCommandNamefR is in dynamic memory
  289. owned by Tcl and is only guaranteed to retain its value as long as the
  290. command isn't deleted or renamed;  callers should copy the string if
  291. they need to keep it for a long time.
  292. .PP
  293. fBTcl_GetCommandFullNamefR produces the fully-qualified name
  294. of a command from a command token.  
  295. The name, including all namespace prefixes,
  296. is appended to the object specified by fIobjPtrfP.
  297. .PP
  298. fBTcl_GetCommandFromObjfR returns a token for the command
  299. specified by the name in a fBTcl_ObjfP.
  300. The command name is resolved relative to the current namespace.
  301. Returns NULL if the command is not found.
  302. .SH "SEE ALSO"
  303. Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
  304. .SH KEYWORDS
  305. bind, command, create, delete, namespace, object