通讯编程

开发平台：
Visual C++

ObjectType.3：源码内容
							'"
'" Copyright (c) 1996-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: ObjectType.3,v 1.7 2002/08/16 13:45:36 dkf Exp $
'" 
.so man.macros
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  - manipulate Tcl object types
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
fBTcl_RegisterObjTypefR(fItypePtrfR)
.sp
Tcl_ObjType *
fBTcl_GetObjTypefR(fItypeNamefR)
.sp
int
fBTcl_AppendAllObjTypesfR(fIinterp, objPtrfR)
.sp
int
fBTcl_ConvertToTypefR(fIinterp, objPtr, typePtrfR)
.SH ARGUMENTS
.AS Tcl_ObjType *typeName in
.AP Tcl_ObjType *typePtr in
Points to the structure containing information about the Tcl object type.
This storage must live forever,
typically by being statically allocated.
.AP "CONST char" *typeName in
The name of a Tcl object type that fBTcl_GetObjTypefR should look up.
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tcl_Obj *objPtr in
For fBTcl_AppendAllObjTypesfR, this points to the object onto which
it appends the name of each object type as a list element.
For fBTcl_ConvertToTypefR, this points to an object that
must have been the result of a previous call to fBTcl_NewObjfR.
.BE
.SH DESCRIPTION
.PP
The procedures in this man page manage Tcl object types.
The are used to register new object types,
look up types,
and force conversions from one type to another.
.PP
fBTcl_RegisterObjTypefR registers a new Tcl object type
in the table of all object types supported by Tcl.
The argument fItypePtrfR points to a Tcl_ObjType structure that
describes the new type by giving its name
and by supplying pointers to four procedures
that implement the type.
If the type table already contains a type
with the same name as in fItypePtrfR,
it is replaced with the new type.
The Tcl_ObjType structure is described
in the section fBTHE TCL_OBJTYPE STRUCTUREfR below.
.PP
fBTcl_GetObjTypefR returns a pointer to the Tcl_ObjType
with name fItypeNamefR.
It returns NULL if no type with that name is registered.
.PP
fBTcl_AppendAllObjTypesfR appends the name of each object type
as a list element onto the Tcl object referenced by fIobjPtrfR.
The return value is fBTCL_OKfR unless there was an error
converting fIobjPtrfR to a list object;
in that case fBTCL_ERRORfR is returned.
.PP
fBTcl_ConvertToTypefR converts an object from one type to another
if possible.
It creates a new internal representation for fIobjPtrfR
appropriate for the target type fItypePtrfR
and sets its fItypePtrfR member to that type.
Any internal representation for fIobjPtrfR's old type is freed.
If an error occurs during conversion, it returns fBTCL_ERRORfR
and leaves an error message in the result object for fIinterpfR
unless fIinterpfR is NULL.
Otherwise, it returns fBTCL_OKfR.
Passing a NULL fIinterpfR allows this procedure to be used
as a test whether the conversion can be done (and in fact was done).
.SH "THE TCL_OBJTYPE STRUCTURE"
.PP
Extension writers can define new object types by defining four
procedures,
initializing a Tcl_ObjType structure to describe the type,
and calling fBTcl_RegisterObjTypefR.
The fBTcl_ObjTypefR structure is defined as follows:
.CS
typedef struct Tcl_ObjType {
	char *fInamefR;
	Tcl_FreeInternalRepProc *fIfreeIntRepProcfR;
	Tcl_DupInternalRepProc *fIdupIntRepProcfR;
	Tcl_UpdateStringProc *fIupdateStringProcfR;
	Tcl_SetFromAnyProc *fIsetFromAnyProcfR;
} Tcl_ObjType;
.CE
.PP
The fInamefR member describes the name of the type, e.g. fBintfR.
Extension writers can look up an object type using its name
with the fBTcl_GetObjTypefR procedure.
The remaining four members are pointers to procedures
called by the generic Tcl object code:
.PP
The fIsetFromAnyProcfR member contains the address of a function
called to create a valid internal representation
from an object's string representation.
.CS
typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *fIinterpfR, Tcl_Obj *fIobjPtrfR);
.CE
If an internal representation can't be created from the string,
it returns fBTCL_ERRORfR and puts a message
describing the error in the result object for fIinterpfR
unless fIinterpfR is NULL.
If fIsetFromAnyProcfR is successful,
it stores the new internal representation,
sets fIobjPtrfR's fItypePtrfR member to point to
fIsetFromAnyProcfR's fBTcl_ObjTypefR, and returns fBTCL_OKfR.
Before setting the new internal representation,
the fIsetFromAnyProcfR must free any internal representation
of fIobjPtrfR's old type;
it does this by calling the old type's fIfreeIntRepProcfR
if it is not NULL.
As an example, the fIsetFromAnyProcfR for the builtin Tcl integer type
gets an up-to-date string representation for fIobjPtrfR
by calling fBTcl_GetStringFromObjfR.
It parses the string to obtain an integer and,
if this succeeds,
stores the integer in fIobjPtrfR's internal representation
and sets fIobjPtrfR's fItypePtrfR member to point to the integer type's
Tcl_ObjType structure.
Do not release fIobjPtrfR's old internal representation unless you
replace it with a new one or reset the fItypePtrfR member to NULL.
.PP
The fIupdateStringProcfR member contains the address of a function
called to create a valid string representation
from an object's internal representation.
.CS
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *fIobjPtrfR);
.CE
fIobjPtrfR's fIbytesfR member is always NULL when it is called.
It must always set fIbytesfR non-NULL before returning.
We require the string representation's byte array
to have a null after the last byte, at offset fIlengthfR;
this allows string representations that do not contain null bytes
to be treated as conventional null character-terminated C strings.
Storage for the byte array must be allocated in the heap by fBTcl_AllocfR
or fBckallocfR.  Note that fIupdateStringProcfRs must allocate
enough storage for the string's bytes and the terminating null byte.
The fIupdateStringProcfR for Tcl's builtin list type, for example,
builds an array of strings for each element object
and then calls fBTcl_MergefR
to construct a string with proper Tcl list structure.
It stores this string as the list object's string representation.
.PP
The fIdupIntRepProcfR member contains the address of a function
called to copy an internal representation from one object to another.
.CS
typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *fIsrcPtrfR, Tcl_Obj *fIdupPtrfR);
.CE
fIdupPtrfR's internal representation is made a copy of fIsrcPtrfR's
internal representation.
Before the call,
fIsrcPtrfR's internal representation is valid and fIdupPtrfR's is not.
fIsrcPtrfR's object type determines what
copying its internal representation means.
For example, the fIdupIntRepProcfR for the Tcl integer type
simply copies an integer.
The builtin list type's fIdupIntRepProcfR
allocates a new array that points at the original element objects;
the elements are shared between the two lists
(and their reference counts are incremented to reflect the new references).
.PP
The fIfreeIntRepProcfR member contains the address of a function
that is called when an object is freed.
.CS
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *fIobjPtrfR);
.CE
The fIfreeIntRepProcfR function can deallocate the storage
for the object's internal representation
and do other type-specific processing necessary when an object is freed.
For example, Tcl list objects have an fIinternalRep.otherValuePtrfR
that points to an array of pointers to each element in the list.
The list type's fIfreeIntRepProcfR decrements
the reference count for each element object
(since the list will no longer refer to those objects),
then deallocates the storage for the array of pointers.
The fIfreeIntRepProcfR member can be set to NULL
to indicate that the internal representation does not require freeing.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
.SH KEYWORDS
internal representation, object, object type, string representation, type conversion

						