Inlets and Outlets
[Classes]

Routines for creating and communicating with inlets and outlets. More...

Collaboration diagram for Inlets and Outlets:

Functions
void *	inlet_new (void x, char s)
	Use inlet_new() to create an inlet that can receive a specific message or any message.
void *	intin (void *x, short n)
	Use intin() to create an inlet typed to receive only integers.
void *	floatin (void *x, short n)
	Use floatin() to create an inlet typed to receive only floats.
void *	outlet_new (void x, char s)
	Use outlet_new() to create an outlet that can send a specific non-standard message, or any message.
void *	bangout (void *x)
	Use bangout() to create an outlet that will always send the bang message.
void *	intout (void *x)
	Use intout() to create an outlet that will always send the int message.
void *	floatout (void *x)
	Use floatout() to create an outlet that will always send the float message.
void *	listout (void *x)
	Use listout() to create an outlet that will always send the list message.
void *	outlet_bang (void *o)
	Use outlet_bang() to send a bang message out an outlet.
void *	outlet_int (void *o, long n)
	Use outlet_int() to send a float message out an outlet.
void *	outlet_float (void *o, double f)
	Use outlet_float() to send an int message out an outlet.
void *	outlet_list (void o, t_symbol s, short ac, t_atom *av)
	Use outlet_list() to send a list message out an outlet.
void *	outlet_anything (void o, t_symbol s, short ac, t_atom *av)
	Use outlet_anything() to send any message out an outlet.
void *	proxy_new (void x, long id, long stuffloc)
	Use proxy_new to create a new Proxy object.
long	proxy_getinlet (t_object *master)
	Use proxy_getinlet to get the inlet number in which a message was received.

Detailed Description

Routines for creating and communicating with inlets and outlets.

Function Documentation

void* bangout ( void * x )

Use bangout() to create an outlet that will always send the bang message.

Parameters:

x

Your object.

Returns:: A pointer to the new outlet.

Remarks:: You can send a bang message out a general purpose outlet, but creating an outlet using bangout() allows Max to type-check the connection a user might make and refuse to connect the outlet to any object that cannot receive a bang message. bangout() returns the created outlet.

void* floatin	(	void *	x,
		short	n
	)

Use floatin() to create an inlet typed to receive only floats.

Parameters:

	x	Your object.
	n	Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet.

Returns:: A pointer to the new inlet.

void* floatout ( void * x )

Use floatout() to create an outlet that will always send the float message.

Parameters:

x

Your object.

Returns:: A pointer to the new outlet.

void* inlet_new	(	void *	x,
		char *	s
	)

Use inlet_new() to create an inlet that can receive a specific message or any message.

Parameters:

	x	Your object.
	s	Character string of the message, or NULL to receive any message.

Returns:: A pointer to the new inlet.

Remarks:

inlet_new() ceates a general purpose inlet. You can use it in circumstances where you would like special messages to be received in inlets other than the leftmost one. To create an inlet that receives a particular message, pass the message’s character string. For example, to create an inlet that receives only bang messages, do the following

    inlet_new (myObject,"bang");

To create an inlet that can receive any message, pass NULL for msg

    inlet_new (myObject, NULL);

Proxies are an alternative method for general-purpose inlets that have a number of advantages. If you create multiple inlets as shown above, there would be no way to figure out which inlet received a message. See the discussion in Creating and Using Proxies.

void* intin	(	void *	x,
		short	n
	)

Use intin() to create an inlet typed to receive only integers.

Parameters:

	x	Your object.
	n	Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet.

Returns:: A pointer to the new inlet.

Remarks:: intin creates integer inlets. It takes a pointer to your newly created object and an integer n, from 1 to 9. The number specifies the message type you’ll get, so you can distinguish one inlet from another. For example, an integer sent in inlet 1 will be of message type in1 and a floating point number sent in inlet 4 will be of type ft4. You use addinx() and addftx() to add methods to respond to these messages.

The order you create additional inlets is important. If you want the rightmost inlet to be the have the highest number in- or ft- message (which is usually the case), you should create the highest number message inlet first.

void* intout ( void * x )

Use intout() to create an outlet that will always send the int message.

Parameters:

x

Your object.

Returns:: A pointer to the new outlet.

Remarks:: You can send a bang message out a general purpose outlet, but creating an outlet using bangout() allows Max to type-check the connection a user might make and refuse to connect the outlet to any object that cannot receive a bang message. bangout() returns the created outlet.

void* listout ( void * x )

Use listout() to create an outlet that will always send the list message.

Parameters:

x

Your object.

Returns:: A pointer to the new outlet.

void* outlet_anything	(	void *	o,
		t_symbol *	s,
		short	ac,
		t_atom *	av
	)

Use outlet_anything() to send any message out an outlet.

Parameters:

	o	Outlet that will send the message.
	s	The message selector t_symbol*.
	ac	Number of elements in the list in argv.
	av	Atoms constituting the list.

Returns:: Returns 0 if a stack overflow occurred, otherwise returns 1.

Remarks:: This function lets you send an arbitrary message out an outlet. Here are a couple of examples of its use.

First, here’s a hard way to send the bang message (see outlet_bang() for an easier way):

    outlet_anything(myOutlet, gensym("bang"), 0, NIL);

Remarks:

And here’s an even harder way to send a single integer (instead of using outlet_int()).

    t_atom myNumber; 

    atom_setlong(&myNumber, 432);
    outlet_anything(myOutlet, gensym("int"), 1, &myNumber);

Notice that outlet_anything() expects the message argument as a t_symbol*, so you must use gensym() on a character string.

If you’ll be sending the same message a lot, you might call gensym() on the message string at initialization time and store the result in a global variable to save the (significant) overhead of calling gensym() every time you want to send a message.

Also, do not send lists using outlet_anything() with list as the selector argument. Use the outlet_list() function instead.

Referenced by max_jit_mop_jit_matrix(), max_jit_mop_outputmatrix(), and max_jit_obex_dumpout().

void* outlet_bang ( void * o )

Use outlet_bang() to send a bang message out an outlet.

Parameters:

o

Outlet that will send the message.

Returns:: Returns 0 if a stack overflow occurred, otherwise returns 1.

void* outlet_float	(	void *	o,
		double	f
	)

Use outlet_float() to send an int message out an outlet.

Parameters:

	o	Outlet that will send the message.
	f	Float value to send.

Returns:: Returns 0 if a stack overflow occurred, otherwise returns 1.

void* outlet_int	(	void *	o,
		long	n
	)

Use outlet_int() to send a float message out an outlet.

Parameters:

	o	Outlet that will send the message.
	n	Integer value to send.

Returns:: Returns 0 if a stack overflow occurred, otherwise returns 1.

void* outlet_list	(	void *	o,
		t_symbol *	s,
		short	ac,
		t_atom *	av
	)

Use outlet_list() to send a list message out an outlet.

Parameters:

	o	Outlet that will send the message.
	s	Should be NULL, but can be the _sym_list.
	ac	Number of elements in the list in argv.
	av	Atoms constituting the list.

Returns:: Returns 0 if a stack overflow occurred, otherwise returns 1.

Remarks:: outlet_list() sends the list specified by argv and argc out the specified outlet. The outlet must have been created with listout or outlet_new in your object creation function (see above). You create the list as an array of Atoms, but the first item in the list must be an integer or float.

Here’s an example of sending a list of three numbers.

    t_atom myList[3]; 
    long theNumbers[3]; 
    short i; 
    
    theNumbers[0] = 23; 
    theNumbers[1] = 12; 
    theNumbers[2] = 5;
    for (i=0; i < 3; i++) { 
        atom_setlong(myList+i,theNumbers[i]);
    } 
    outlet_list(myOutlet,0L,3,&myList);

Remarks:: It’s not a good idea to pass large lists to outlet_list that are comprised of local (automatic) variables. If the list is small, as in the above example, there’s no problem. If your object will regularly send lists, it might make sense to keep an array of t_atoms inside your object’s data structure.

void* outlet_new	(	void *	x,
		char *	s
	)

Use outlet_new() to create an outlet that can send a specific non-standard message, or any message.

Parameters:

	x	Your object.
	s	A C-string specifying the message that will be sent out this outlet, or NULL to indicate the outlet will be used to send various messages. The advantage of this kind of outlet’s flexibility is balanced by the fact that Max must perform a message-lookup in real-time for every message sent through it, rather than when a patch is being constructed, as is true for other types of outlets. Patchers execute faster when outlets are typed, since the message lookup can be done before the program executes.

Returns:: A pointer to the new outlet.

Referenced by max_jit_mop_matrixout_new(), and max_jit_mop_setup_simple().

long proxy_getinlet ( t_object * master )

Use proxy_getinlet to get the inlet number in which a message was received.

Note that the “owner” argument should point to your external object’s instance, not a proxy object.

Parameters:

master

Your object.

Returns:: The index number of the inlet that received the message.

Referenced by max_jit_obex_inletnumber_get().

void* proxy_new	(	void *	x,
		long	id,
		long *	stuffloc
	)

Use proxy_new to create a new Proxy object.

Parameters:

	x	Your object.
	id	A non-zero number to be written into your object when a message is received in this particular Proxy. Normally, id will be the inlet “number” analogous to in1, in2 etc.
	stuffloc	A pointer to a location where the id value will be written.

Returns:: A pointer to the new proxy inlet.

Remarks:: This routine creates a new Proxy object (that includes an inlet). It allows you to identify messages based on an id value stored in the location specified by stuffLoc. You should store the pointer returned by proxy_new() because you’ll need to free all Proxies in your object’s free function using object_free().

After your method has finished, Proxy sets the stuffLoc location back to 0, since it never sees messages coming in an object’s leftmost inlet. You’ll know you received a message in the leftmost inlet if the contents of stuffLoc is 0. As of Max 4.3, stuffLoc is not always guaranteed to be a correct indicator of the inlet in which a message was received. Use proxy_getinlet() to determine the inlet number.

Referenced by max_jit_obex_proxy_new().

Inlets and Outlets [Classes]

Functions

Detailed Description

Function Documentation

Inlets and Outlets
[Classes]