Data Structures
struct	t_messlist
	A list of symbols and their corresponding methods, complete with typechecking information. More...
struct	t_tinyobject
	The tiny object structure sits at the head of any object to which you may pass messages (and which you may feed to freeobject()). More...
struct	t_object
	The structure for the head of any object which wants to have inlets or outlets, or support attributes. More...
Defines
#define	MAGIC
	Magic number used to determine if memory pointed to by a t_object* is valid.
#define	NOGOOD(x)
	Returns true if a pointer is not a valid object.
#define	MAXARG
	Maximum number of arguments that can be passed as a typed-list rather than using A_GIMME.
Functions
t_object *	newobject_sprintf (t_object patcher, C74_CONST char fmt,...)
	Create a new object in a specified patcher with values using a combination of attribute and sprintf syntax.
t_object *	newobject_fromdictionary (t_object patcher, t_dictionary d)
	Place a new object into a patcher.
long	object_classname_compare (void x, t_symbol name)
	Determines if a particular object is an instance of a given class.
void *	object_alloc (t_class *c)
	Allocates the memory for an instance of an object class and initialize its object header.
void *	object_new (t_symbol name_space, t_symbol classname,...)
	Allocates the memory for an instance of an object class and initialize its object header internal to Max.
void *	object_new_typed (t_symbol name_space, t_symbol classname, long ac, t_atom *av)
	Allocates the memory for an instance of an object class and initialize its object header internal to Max.
t_max_err	object_free (void *x)
	Call the free function and release the memory for an instance of an internal object class previously instantiated using object_new(), object_new_typed() or other new-style object constructor functions (e.g.
void *	object_method (void x, t_symbol s,...)
	Sends an untyped message to an object.
t_max_err	object_method_typed (void x, t_symbol s, long ac, t_atom av, t_atom rv)
	Sends a type-checked message to an object.
t_max_err	object_method_typedfun (void x, t_messlist mp, t_symbol s, long ac, t_atom av, t_atom *rv)
	Currently undocumented.
method	object_getmethod (void x, t_symbol s)
	Retrieves an object's method for a particular message selector.
t_symbol *	object_classname (void *x)
	Retrieves an object instance's class name.
void *	object_register (t_symbol name_space, t_symbol s, void *x)
	Registers an object in a namespace.
void *	object_findregistered (t_symbol name_space, t_symbol s)
	Determines a registered object's pointer, given its namespace and name.
t_max_err	object_findregisteredbyptr (t_symbol name_space, t_symbol s, void *x)
	Determines the namespace and/or name of a registered object, given the object's pointer.
void *	object_attach (t_symbol name_space, t_symbol s, void *x)
	Attaches a client to a registered object.
t_max_err	object_detach (t_symbol name_space, t_symbol s, void *x)
	Detach a client from a registered object.
t_max_err	object_attach_byptr (void x, void registeredobject)
	Attaches a client to a registered object.
t_max_err	object_attach_byptr_register (void x, void object_to_attach, t_symbol *reg_name_space)
	A convenience function wrapping object_register() and object_attach_byptr().
t_max_err	object_detach_byptr (void x, void registeredobject)
	Detach a client from a registered object.
void *	object_subscribe (t_symbol name_space, t_symbol s, t_symbol classname, void x)
	Subscribes a client to wait for an object to register.
t_max_err	object_unsubscribe (t_symbol name_space, t_symbol s, t_symbol classname, void x)
	Unsubscribe a client from a registered object, detaching if the object is registered.
t_max_err	object_unregister (void *x)
	Removes a registered object from a namespace.
t_max_err	object_register_getnames (t_symbol name_space, long namecount, t_symbol ***names)
	Returns all registered names in a namespace.
t_max_err	object_notify (void x, t_symbol s, void *data)
	Broadcast a message (with an optional argument) from a registered object to any attached client objects.
t_class *	object_class (void *x)
	Determines the class of a given object.
t_max_err	object_getvalueof (void x, long ac, t_atom **av)
	Retrieves the value of an object which supports the `getvalueof/setvalueof` interface.
t_max_err	object_setvalueof (void x, long ac, t_atom av)
	Sets the value of an object which supports the `getvalueof/setvalueof` interface.
t_max_err	object_obex_lookup (void x, t_symbol key, t_object **val)
	Retrieves the value of a data stored in the obex.
t_max_err	object_obex_store (void x, t_symbol key, t_object *val)
	Stores data in the object's obex.
void	object_obex_dumpout (void x, t_symbol s, long argc, t_atom *argv)
	Sends data from the object's dumpout outlet.
t_dictionary *	object_dictionaryarg (long ac, t_atom *av)
	Retrieve a pointer to a dictionary passed in as an atom argument.
void *	object_super_method (t_object x, t_symbol s,...)
	Sends an untyped message to an object using superclass methods.
void *	object_this_method (t_object x, t_symbol s,...)
	Sends an untyped message to an object, respects a thread specific class stack from object_super_method() calls.
t_max_err	object_attr_touch (t_object x, t_symbol attrname)
	Mark an attribute as being touched by some code not from the attribute setter.
t_max_err	object_attr_touch_parse (t_object x, char attrnames)
	Mark one or more attributes as being touched by some code not from the attribute setter.
t_max_err	object_method_parse (t_object x, t_symbol s, C74_CONST char parsestr, t_atom rv)
	Convenience wrapper for object_method_typed() that uses atom_setparse() to define the arguments.
t_max_err	object_method_format (t_object x, t_symbol s, t_atom rv, C74_CONST char fmt,...)
	Convenience wrapper for object_method_typed() that uses atom_setformat() to define the arguments.
t_max_err	object_method_char (t_object x, t_symbol s, unsigned char v, t_atom *rv)
	Convenience wrapper for object_method_typed() that passes a single char as an argument.
t_max_err	object_method_long (t_object x, t_symbol s, long v, t_atom *rv)
	Convenience wrapper for object_method_typed() that passes a single long integer as an argument.
t_max_err	object_method_float (t_object x, t_symbol s, float v, t_atom *rv)
	Convenience wrapper for object_method_typed() that passes a single 32bit float as an argument.
t_max_err	object_method_double (t_object x, t_symbol s, double v, t_atom *rv)
	Convenience wrapper for object_method_typed() that passes a single 64bit float as an argument.
t_max_err	object_method_sym (t_object x, t_symbol s, t_symbol v, t_atom rv)
	Convenience wrapper for object_method_typed() that passes a single t_symbol* as an argument.
t_max_err	object_method_obj (t_object x, t_symbol s, t_object v, t_atom rv)
	Convenience wrapper for object_method_typed() that passes a single t_object* as an argument.
t_max_err	object_method_char_array (t_object x, t_symbol s, long ac, unsigned char av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of char values as an argument.
t_max_err	object_method_long_array (t_object x, t_symbol s, long ac, long av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of long integers values as an argument.
t_max_err	object_method_float_array (t_object x, t_symbol s, long ac, float av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of 32bit floats values as an argument.
t_max_err	object_method_double_array (t_object x, t_symbol s, long ac, double av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of 64bit float values as an argument.
t_max_err	object_method_sym_array (t_object x, t_symbol s, long ac, t_symbol *av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of t_symbol* values as an argument.
t_max_err	object_method_obj_array (t_object x, t_symbol s, long ac, t_object *av, t_atom rv)
	Convenience wrapper for object_method_typed() that passes an array of t_object* values as an argument.
void	object_openhelp (t_object *x)
	Open the help patcher for a given instance of an object.
void	object_openrefpage (t_object *x)
	Open the reference page for a given instance of an object.
void	object_openquery (t_object *x)
	Open a search in the file browser for files with the name of the given object.
void	classname_openhelp (char *classname)
	Open the help patcher for a given object class name.
void	classname_openrefpage (char *classname)
	Open the reference page for a given object class name.
void	classname_openquery (char *classname)
	Open a search in the file browser for files with the name of the given class.

Detailed Description

See also:: http://www.cycling74.com/twiki/bin/view/ProductDocumentation/JitterSdkObjectModel; http://www.cycling74.com/twiki/bin/view/ProductDocumentation/JitterSdkRegNotify

Define Documentation

#define MAXARG

Maximum number of arguments that can be passed as a typed-list rather than using A_GIMME.

It is generally recommended to use A_GIMME.

Function Documentation

void classname_openhelp ( char * classname )

Open the help patcher for a given object class name.

Parameters:

classname The class name for which to open the help patcher.

void classname_openquery ( char * classname )

Open a search in the file browser for files with the name of the given class.

Parameters:

classname The class name for which to query.

void classname_openrefpage ( char * classname )

Open the reference page for a given object class name.

Parameters:

classname The class name for which to open the reference page.

t_object* newobject_fromdictionary	(	t_object *	patcher,
		t_dictionary *	d
	)

Place a new object into a patcher.

The new object will be created based on a specification contained in a Dictionary.

Create a new dictionary populated with values using a combination of attribute and sprintf syntax.

Parameters:

patcher	An instance of a patcher object.
d	A dictionary containing an object specification.

Returns:: A pointer to the newly created object instance, or NULL if creation of the object fails.

Remarks:

Max attribute syntax is used to define key-value pairs. For example,

    "@key1 value @key2 another_value"

The example below creates a new object that in a patcher whose object pointer is stored in a variable called "aPatcher".

    t_dictionary *d;
    t_object *o;
    char text[4];
    
    strncpy_zero(text, "foo", 4);

    d = dictionary_sprintf("@maxclass comment @varname _name \
        @text \"%s\" @patching_rect %.2f %.2f %.2f %.2f \
        @fontsize %f @textcolor %f %f %f 1.0 \
        @fontname %s @bgcolor 0.001 0.001 0.001 0.",
        text, 20.0, 20.0, 200.0, 24.0,
        18, 0.9, 0.9, 0.9, "Arial");
    
    o = newobject_fromdictionary(aPatcher, d);

See also:: newobject_sprintf(); newobject_fromdictionary(); atom_setparse()

t_object* newobject_sprintf	(	t_object *	patcher,
		C74_CONST char *	fmt,
			...
	)

Create a new object in a specified patcher with values using a combination of attribute and sprintf syntax.

Parameters:

patcher	An instance of a patcher object.
fmt	An sprintf-style format string specifying key-value pairs with attribute nomenclature.
...	One or more arguments which are to be substituted into the format string.

Returns:: A pointer to the newly created object instance, or NULL if creation of the object fails.

Remarks:

Max attribute syntax is used to define key-value pairs. For example,

    "@key1 value @key2 another_value"

The example below creates a new object that in a patcher whose object pointer is stored in a variable called "aPatcher".

    t_object *my_comment;
    char text[4];
    
    strncpy_zero(text, "foo", 4);

    my_comment = newobject_sprintf(aPatcher, "@maxclass comment @varname _name \
        @text \"%s\" @patching_rect %.2f %.2f %.2f %.2f \
        @fontsize %f @textcolor %f %f %f 1.0 \
        @fontname %s @bgcolor 0.001 0.001 0.001 0.",
        text, 20.0, 20.0, 200.0, 24.0,
        18, 0.9, 0.9, 0.9, "Arial");

See also:: dictionary_sprintf(); newobject_fromdictionary(); atom_setparse()

void* object_alloc ( t_class * c )

Allocates the memory for an instance of an object class and initialize its object header.

It is used like the traditional function newobject, inside of an object's new method, but its use is required with obex-class objects.

Parameters:

c	The class pointer, returned by class_new()

Returns:: This function returns a new instance of an object class if successful, or NULL if unsuccessful.

void* object_attach	(	t_symbol *	name_space,
		t_symbol *	s,
		void *	x
	)

Attaches a client to a registered object.

Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), if it has a notify method defined and implemented.

Parameters:

name_space	The namespace of the registered object. This should be the same value used in object_register() to register the object. If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it.
s	The name of the registered object in the namespace. If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it.
x	The client object to attach. Generally, this is the pointer to your Max object.

Returns:: This function returns a pointer to the registered object (to the object referred to by the combination of name_space and s arguments) if successful, or NULL if unsuccessful.

Remarks:: You should not attach an object to itself if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().

See also:: object_notify(); object_detach(); object_attach_byptr(); object_register()

t_max_err object_attach_byptr	(	void *	x,
		void *	registeredobject
	)

Attaches a client to a registered object.

Unlike object_attach(), the client is specified by providing a pointer to that object rather than the registered name of that object.

Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), if it has a notify method defined and implemented.

Parameters:

x	The attaching client object. Generally, this is the pointer to your Max object.
registeredobject	A pointer to the registered object to which you wish to attach.

Returns:: A Max error code.

Remarks:: You should not attach an object to itself if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().

See also:: object_notify(); object_detach(); object_attach(); object_register(); object_attach_byptr_register()

t_max_err object_attach_byptr_register	(	void *	x,
		void *	object_to_attach,
		t_symbol *	reg_name_space
	)

A convenience function wrapping object_register() and object_attach_byptr().

Parameters:

x	The attaching client object. Generally, this is the pointer to your Max object.
object_to_attach	A pointer to the object to which you wish to registered and then to which to attach.
reg_name_space	The namespace in which to register the object_to_attach.

Returns:: A Max error code.

See also:: object_register(); object_attach_byptr()

t_max_err object_attr_touch	(	t_object *	x,
		t_symbol *	attrname
	)

Mark an attribute as being touched by some code not from the attribute setter.

This will notify clients that the attribute has changed.

Parameters:

x	The object whose attribute has been changed
attrname	The attribute name

Returns:: A Max error code

t_max_err object_attr_touch_parse	(	t_object *	x,
		char *	attrnames
	)

Mark one or more attributes as being touched by some code not from the attribute setter.

This will notify clients that the attributes have changed. Utility to call object_attr_touch() for several attributes

Parameters:

x	The object whose attribute has been changed
attrnames	The attribute names as a space separated string

Returns:: A Max error code

t_class* object_class ( void * x )

Determines the class of a given object.

Parameters:

x	The object to test

Returns:: This function returns the t_class * of the object's class, if successful, or NULL, if unsuccessful.

t_symbol* object_classname ( void * x )

Retrieves an object instance's class name.

Parameters:

x	The object instance whose class name is being queried

Returns:: The classname, or NULL if unsuccessful.

long object_classname_compare	(	void *	x,
		t_symbol *	name
	)

Determines if a particular object is an instance of a given class.

Parameters:

x	The object to test
name	The name of the class to test this object against

Returns:: This function returns 1 if the object is an instance of the named class. Otherwise, 0 is returned.

Remarks:: For instance, to determine whether an unknown object pointer is a pointer to a print object, one would call:

    long isprint = object_classname_compare(x, gensym("print"));

t_max_err object_detach	(	t_symbol *	name_space,
		t_symbol *	s,
		void *	x
	)

Detach a client from a registered object.

Parameters:

name_space	The namespace of the registered object. This should be the same value used in object_register() to register the object. If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it.
s	The name of the registered object in the namespace. If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it.
x	The client object to attach. Generally, this is the pointer to your Max object.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

t_max_err object_detach_byptr	(	void *	x,
		void *	registeredobject
	)

Detach a client from a registered object.

Parameters:

x	The attaching client object. Generally, this is the pointer to your Max object.
registeredobject	The object from which to detach.

Returns:: A Max error code.

See also:: object_detach(); object_attach_byptr()

t_dictionary* object_dictionaryarg	(	long	ac,
		t_atom *	av
	)

Retrieve a pointer to a dictionary passed in as an atom argument.

Use this function when working with classes that have dictionary constructors to fetch the dictionary.

Parameters:

ac	The number of atoms.
av	A pointer to the first atom in the array.

Returns:: The dictionary retrieved from the atoms.

See also:: attr_dictionary_process()

void* object_findregistered	(	t_symbol *	name_space,
		t_symbol *	s
	)

Determines a registered object's pointer, given its namespace and name.

Parameters:

name_space	The namespace of the registered object
s	The name of the registered object in the namespace

Returns:: This function returns the pointer of the registered object, if successful, or NULL, if unsuccessful.

t_max_err object_findregisteredbyptr	(	t_symbol **	name_space,
		t_symbol **	s,
		void *	x
	)

Determines the namespace and/or name of a registered object, given the object's pointer.

Parameters:

name_space	Pointer to a t_symbol *, to receive the namespace of the registered object
s	Pointer to a t_symbol *, to receive the name of the registered object within the namespace
x	Pointer to the registered object

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

t_max_err object_free ( void * x )

Call the free function and release the memory for an instance of an internal object class previously instantiated using object_new(), object_new_typed() or other new-style object constructor functions (e.g.

hashtab_new()). It is, at the time of this writing, a wrapper for the traditional function freeobject(), but its use is suggested with obex-class objects.

Parameters:

x	The pointer to the object to be freed.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

method object_getmethod	(	void *	x,
		t_symbol *	s
	)

Retrieves an object's method for a particular message selector.

Parameters:

x	The object whose method is being queried
s	The message selector

Returns:: This function returns the method if successful, or method_false() if unsuccessful.

t_max_err object_getvalueof	(	void *	x,
		long *	ac,
		t_atom **	av
	)

Retrieves the value of an object which supports the getvalueof/setvalueof interface.

See part 2 of the pattr SDK for more information on this interface.

Parameters:

x	The object whose value is of interest
ac	Pointer to a long variable to receive the count of arguments in `av`. The long variable itself should be set to 0 previous to calling this function.
av	Pointer to a t_atom , to receive object data. The t_atom itself should be set to NULL previous to calling this function.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:

Calling the object_getvalueof() function allocates memory for any data it returns. It is the developer's responsibility to free it, using the freebytes() function.

Developers wishing to design objects which will support this function being called on them must define and implement a special method, getvalueof, like so:

    class_addmethod(c, (method)myobject_getvalueof, "getvalueof", A_CANT, 0);

The getvalueof method should be prototyped as:

    t_max_err myobject_getvalueof(t_myobject *x, long *ac, t_atom **av);

And implemented, generally, as:

    t_max_err myobj_getvalueof(t_myobj *x, long *ac, t_atom **av) 
    {
        if (ac && av) {
            if (*ac && *av) {
                // memory has been passed in; use it.
            } else {
                // allocate enough memory for your data
                *av = (t_atom *)getbytes(sizeof(t_atom));
            }
            *ac = 1; // our data is a single floating point value
            atom_setfloat(*av, x->objvalue);
        }
        return MAX_ERR_NONE;
    }

    @remark         By convention, and to permit the interoperability of objects using the obex API, 
                    developers should allocate memory in their <tt>getvalueof</tt> methods using the getbytes() function.

void* object_method	(	void *	x,
		t_symbol *	s,
			...
	)

Sends an untyped message to an object.

Parameters:

x	The object that will receive the message
s	The message selector
...	Any arguments to the message

Returns:: If the receiver object can respond to the message, object_method() returns the result. Otherwise, the function will return 0.

Remarks:

Example: To send the message bang to the object bang_me:

    void *bang_result;
    bang_result = object_method(bang_me, gensym("bang"));

t_max_err object_method_char	(	t_object *	x,
		t_symbol *	s,
		unsigned char	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single char as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_char_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		unsigned char *	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of char values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_double	(	t_object *	x,
		t_symbol *	s,
		double	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single 64bit float as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_double_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		double *	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of 64bit float values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_float	(	t_object *	x,
		t_symbol *	s,
		float	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single 32bit float as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_float_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		float *	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of 32bit floats values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_format	(	t_object *	x,
		t_symbol *	s,
		t_atom *	rv,
		C74_CONST char *	fmt,
			...
	)

Convenience wrapper for object_method_typed() that uses atom_setformat() to define the arguments.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
rv	The address of an atom to hold a return value.
fmt	An sprintf-style format string specifying values for the atoms.
...	One or more arguments which are to be substituted into the format string.

Returns:: A Max error code.

See also:: object_method_typed(); atom_setformat()

t_max_err object_method_long	(	t_object *	x,
		t_symbol *	s,
		long	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single long integer as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_long_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		long *	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of long integers values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_obj	(	t_object *	x,
		t_symbol *	s,
		t_object *	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single t_object* as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_obj_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		t_object **	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of t_object* values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_parse	(	t_object *	x,
		t_symbol *	s,
		C74_CONST char *	parsestr,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that uses atom_setparse() to define the arguments.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
parsestr	A C-string to parse into an array of atoms to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed(); atom_setparse()

t_max_err object_method_sym	(	t_object *	x,
		t_symbol *	s,
		t_symbol *	v,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes a single t_symbol* as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
v	An argument to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_sym_array	(	t_object *	x,
		t_symbol *	s,
		long	ac,
		t_symbol **	av,
		t_atom *	rv
	)

Convenience wrapper for object_method_typed() that passes an array of t_symbol* values as an argument.

Parameters:

x	The object to which the message will be sent.
s	The name of the method to call on the object.
ac	The number of arguments to pass to the method.
av	The address of the first of the array of arguments to pass to the method.
rv	The address of an atom to hold a return value.

Returns:: A Max error code.

See also:: object_method_typed()

t_max_err object_method_typed	(	void *	x,
		t_symbol *	s,
		long	ac,
		t_atom *	av,
		t_atom *	rv
	)

Sends a type-checked message to an object.

Parameters:

x	The object that will receive the message
s	The message selector
ac	Count of message arguments in `av`
av	Array of t_atoms; the message arguments
rv	Return value of function, if available

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:: If the receiver object can respond to the message, object_method_typed() returns the result in rv. Otherwise, rv will contain an A_NOTHING atom.

t_max_err object_method_typedfun	(	void *	x,
		t_messlist *	mp,
		t_symbol *	s,
		long	ac,
		t_atom *	av,
		t_atom *	rv
	)

Currently undocumented.

Parameters:

x	The object that will receive the message
mp	Undocumented
s	The message selector
ac	Count of message arguments in `av`
av	Array of t_atoms; the message arguments
rv	Return value of function, if available

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:: If the receiver object can respond to the message, object_method_typedfun() returns the result in rv. Otherwise, rv will contain an A_NOTHING atom.

void* object_new	(	t_symbol *	name_space,
		t_symbol *	classname,
			...
	)

Allocates the memory for an instance of an object class and initialize its object header internal to Max.

It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects.

Parameters:

name_space	The desired object's name space. Typically, either the constant CLASS_BOX, for obex classes which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant CLASS_NOBOX, for classes which will only be used internally. Developers can define their own name spaces as well, but this functionality is currently undocumented.
classname	The name of the class of the object to be created
...	Any arguments expected by the object class being instantiated

Returns:: This function returns a new instance of the object class if successful, or NULL if unsuccessful.

void* object_new_typed	(	t_symbol *	name_space,
		t_symbol *	classname,
		long	ac,
		t_atom *	av
	)

Allocates the memory for an instance of an object class and initialize its object header internal to Max.

It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects. The object_new_typed() function differs from object_new() by its use of an atom list for object arguments—in this way, it more resembles the effect of typing something into an object box from the Max interface.

Parameters:

name_space	The desired object's name space. Typically, either the constant CLASS_BOX, for obex classes which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant CLASS_NOBOX, for classes which will only be used internally. Developers can define their own name spaces as well, but this functionality is currently undocumented.
classname	The name of the class of the object to be created
ac	Count of arguments in `av`
av	Array of t_atoms; arguments to the class's instance creation function.

Returns:: This function returns a new instance of the object class if successful, or NULL if unsuccessful.

t_max_err object_notify	(	void *	x,
		t_symbol *	s,
		void *	data
	)

Broadcast a message (with an optional argument) from a registered object to any attached client objects.

Parameters:

x	Pointer to the registered object
s	The message to send
data	An optional argument which will be passed with the message. Sets this argument to NULL if it will be unused.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:

In order for client objects to receive notifications, they must define and implement a special method, notify, like so:

    class_addmethod(c, (method)myobject_notify, "notify", A_CANT, 0);

The notify method should be prototyped as:

    void myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender, void *data);

where x is the pointer to the receiving object, s is the name of the sending (registered) object in its namespace, msg is the sent message, sender is the pointer to the sending object, and data is an optional argument sent with the message. This value corresponds to the data argument in the object_notify() method.

void object_obex_dumpout	(	void *	x,
		t_symbol *	s,
		long	argc,
		t_atom *	argv
	)

Sends data from the object's dumpout outlet.

The dumpout outlet is stored in the obex using the object_obex_store() function (see above). It is used approximately like outlet_anything().

Parameters:

x	The object pointer. This function should only be called on instantiated objects (i.e. in the `new` method or later), not directly on classes (i.e. in `main()`).
s	The message selector t_symbol *
argc	Number of elements in the argument list in argv
argv	t_atoms constituting the message arguments

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

t_max_err object_obex_lookup	(	void *	x,
		t_symbol *	key,
		t_object **	val
	)

Retrieves the value of a data stored in the obex.

Parameters:

x	The object pointer. This function should only be called on instantiated objects (i.e. in the `new` method or later), not directly on classes (i.e. in `main()`).
key	The symbolic name for the data to be retrieved
val	A pointer to a t_object *, to be filled with the data retrieved from the obex.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:

By default, pointers to the object's containing patcher and box objects are stored in the obex, under the keys '#P' and '#B', respectively. To retrieve them, the developer could do something like the following:

    void post_containers(t_obexobj *x)
    {
        t_patcher *p;
        t_box *b;
        t_max_err err;

        err = object_obex_lookup(x, gensym("#P"), (t_object **)&p);
        err = object_obex_lookup(x, gensym("#B"), (t_object **)&b);

        post("my patcher is located at 0x%X", p);
        post("my box is located at 0x%X", b);
    }

t_max_err object_obex_store	(	void *	x,
		t_symbol *	key,
		t_object *	val
	)

Stores data in the object's obex.

Parameters:

x	The object pointer. This function should only be called on instantiated objects (i.e. in the `new` method or later), not directly on classes (i.e. in `main()`).
key	A symbolic name for the data to be stored
val	A t_object *, to be stored in the obex, referenced under the `key`.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:

Most developers will need to use this function for the specific purpose of storing the dumpout outlet in the obex (the dumpout outlet is used by attributes to report data in response to 'get' queries). For this, the developer should use something like the following in the object's new method:

    object_obex_store(x, _sym_dumpout, outlet_new(x, NULL));

void object_openhelp ( t_object * x )

Open the help patcher for a given instance of an object.

Parameters:

x	The object instance for which to open the help patcher.

void object_openquery ( t_object * x )

Open a search in the file browser for files with the name of the given object.

Parameters:

x	The object instance for which to query.

void object_openrefpage ( t_object * x )

Open the reference page for a given instance of an object.

Parameters:

x	The object instance for which to open the reference page.

void* object_register	(	t_symbol *	name_space,
		t_symbol *	s,
		void *	x
	)

Registers an object in a namespace.

Parameters:

name_space	The namespace in which to register the object. The namespace can be any symbol. If the namespace does not already exist, it is created automatically.
s	The name of the object in the namespace. This name will be used by other objects to attach and detach from the registered object.
x	The object to register

Returns:: The function returns a pointer to the registered object. Under some circumstances, object_register will duplicate the object, and return a pointer to the duplicate—the developer should not assume that the pointer passed in is the same pointer that has been registered. To be safe, the returned pointer should be stored and used with the bject_unregister() function.

Remarks:: You should not register an object if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().

t_max_err object_register_getnames	(	t_symbol *	name_space,
		long *	namecount,
		t_symbol ***	names
	)

Returns all registered names in a namespace.

Parameters:

name_space	Pointer to a t_symbol, the namespace to lookup names in
namecount	Pointer to a long, to receive the count of the registered names within the namespace
names	Pointer to a t_symbol **, to receive the allocated names. This pointer should be freed after use

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in "ext_obex.h" if unsuccessful.

t_max_err object_setvalueof	(	void *	x,
		long	ac,
		t_atom *	av
	)

Sets the value of an object which supports the getvalueof/setvalueof interface.

Parameters:

x	The object whose value is of interest
ac	The count of arguments in `av`
av	Array of t_atoms; the new desired data for the object

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Remarks:

Developers wishing to design objects which will support this function being called on them must define and implement a special method, setvalueof, like so:

    class_addmethod(c, (method)myobject_setvalueof, "setvalueof", A_CANT, 0);

The setvalueof method should be prototyped as:

    t_max_err myobject_setvalueof(t_myobject *x, long *ac, t_atom **av);

And implemented, generally, as:

    t_max_err myobject_setvalueof(t_myobject *x, long ac, t_atom *av)
    {
        if (ac && av) {
            // simulate receipt of a float value
            myobject_float(x, atom_getfloat(av));
        }
        return MAX_ERR_NONE;
    }

void* object_subscribe	(	t_symbol *	name_space,
		t_symbol *	s,
		t_symbol *	classname,
		void *	x
	)

Subscribes a client to wait for an object to register.

Upon registration, the object will attach. Once attached, the object will receive notifications sent from the registered object (via the object_notify function), if it has a notify method defined and implemented. See below for more information, in the reference for object_notify.

Parameters:

name_space	The namespace of the registered object. This should be the same value used in `object_register` to register the object. If you don't know the registered object's namespace, the `object_findregisteredbyptr` function can be used to determine it.
s	The name of the registered object in the namespace. If you don't know the name of the registered object, the `object_findregisteredbyptr` function can be used to determine it.
classname	The classname of the registered object in the namespace to use as a filter. If NULL, then it will attach to any class of object.
x	The client object to attach. Generally, this is the pointer to your Max object.

Returns:: This function returns a pointer to the object if registered (to the object referred to by the combination of name_space and s arguments) if successful, or NULL if the object is not yet registered.

void* object_super_method	(	t_object *	x,
		t_symbol *	s,
			...
	)

Sends an untyped message to an object using superclass methods.

Uses a thread specific stack to ensure traversal up the class hierarchy.

Parameters:

x	The object that will receive the message
s	The message selector
...	Any arguments to the message

Returns:: If the receiver object can respond to the message, object_method() returns the result. Otherwise, the function will return 0.

void* object_this_method	(	t_object *	x,
		t_symbol *	s,
			...
	)

Sends an untyped message to an object, respects a thread specific class stack from object_super_method() calls.

Parameters:

x	The object that will receive the message
s	The message selector
...	Any arguments to the message

Returns:: If the receiver object can respond to the message, object_method() returns the result. Otherwise, the function will return 0.

t_max_err object_unregister ( void * x )

Removes a registered object from a namespace.

Parameters:

x	The object to unregister. This should be the pointer returned from the object_register() function.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

t_max_err object_unsubscribe	(	t_symbol *	name_space,
		t_symbol *	s,
		t_symbol *	classname,
		void *	x
	)

Unsubscribe a client from a registered object, detaching if the object is registered.

Parameters:

name_space	The namespace of the registered object. This should be the same value used in `object_register` to register the object. If you don't know the registered object's namespace, the `object_findregisteredbyptr` function can be used to determine it.
s	The name of the registered object in the namespace. If you don't know the name of the registered object, the `object_findregisteredbyptr` function can be used to determine it.
classname	The classname of the registered object in the namespace to use as a filter. Currently unused for unsubscribe.
x	The client object to detach. Generally, this is the pointer to your Max object.

Returns:: This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in "ext_obex.h" if unsuccessful.

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation