osContStartQuery, osContGetQuery

Gets Status and Type of SI Device

Syntax

#include <ultra64.h> /* os.h */ s32
osContStartQuery(OSMesgQueue *mq); void
osContGetQuery(OSContStatus *status);

Description

The osContStartQuery function starts to read the values for SI device status and type which is connected to the controller port and the joyport connector. The osContGetQuery function returns those values to status. By calling these two functions, such status can be obtained that a standard Controller is connected to the controller port or that a Controller Pak is inserted to the joyport connector. These two functions must be paired for use.

The message queue, mq, must be the initialized message queue linked to OS_EVENT_SI. See the osSetEventMesg function in the N64 Online Function Reference Manual to learn how to create this link.

The osContStartQuery function is called only to issue read command, and the message for completed data reading is returned to the message queue mq. Therefore, the osContGetQuery function should be called to obtain data after the osContStartQuery function is called, and osRecvMesg receives a message indicating data reading is completed. The osContStartQuery function takes around 2 milliseconds to complete its data reading and for osRecvMesg to receive a final message. Other process such as re-drawing the screen can be performed while you are waiting.

You must supply a memory block large enough for MAXCONTROLLER structures of type osContStatus. Regarding the osContSetCh() function, it is fine to set the number of direct-type SI devices to be used, to a value less than the value set for MAXCONTROLLERS, if the number of direct-type devices used will not be changed in the future.

typedef struct {
    u16     type; 	/* Controller Type */
    u8      status;	/* Joyport Status */
    u8      errno;	/* error from device */
}OSContStatus;

One of the following bit is set to 1 to the value for status->type, depending on which kind of direct- SI device is inserted to the controller port. 0 is returned when no device is inserted to the controller port.

CONT_ABSOLUTE

This bit is set to 1 when a Standard Controller is connected to the N64 Control Deck. The connected device is judged to be a Controller if the device has a built-in absolute value counter for counting the amount of movement of the control stick as an absolute value from the origin. As of December 1998, this bit is only set when the Controller is attached.

CONT_RELATIVE

This bit is set to 1 when the mouse is attached. The connected device is judged to be a mouse if the device has a built-in relative counter for counting the amount of movement of the mouse from the current coordinates. As of December 1998, this bit is only set when the mouse is attached.

CONT_JOYPORT

This bit is set to 1 when a joyport is attached to the direct-type SI device that is connected to the Controller Port. As of December 1998, the only SI device with a joyport is the Standard Controller.

Confirm which kind of direct-type SI device is connected to the Controller Port in the following way:

• If the status->type value masked with CONT_TYPE_MASK is equal to CONT_TYPE_NORMAL, then a Standard Controller is connected. (When a Standard Controller is connected, the bits are set to 1 for both CONT_ABSOLUTE and CONT_JOYPORT in status->type. CONT_TYPE_NORMAL includes the bits for both CONT_ABSOLUTE and CONT_JOYPORT.)

• If the masked value is equal to CONT_TYPE_MOUSE, that means a mouse is connected.

• And if it is equal to CONT_TYPE_VOICE it means the Voice Recognition System is connected.

If the direct-type SI device connected to the Controller Port is a Standard Controller, then the status of that joyport can be checked with status->status. The lower bit in status->status is set to 1. If nothing is inserted in either the Controller Port or the joyport connector, or if a direct-type SI device that is not a Controller is inserted, then 0 is returned.

CONT_CARD_ON

This bit is set when a device has been inserted.

CONT_CARD_PULL

This bit is set when the device has been removed.

An Error value is set to status->errno when the function fails to read the status value of SI device. 0 is returned if the function was successful. One of the follwing values is returned should an error occur.

CONT_NO_RESPONSE_ERROR

There is no response from the Controller. The Controller is not inserted.

CONT_OVERRUN_ERROR

The controller sends data at a higher data transfer rate than the hardware can handle. In this case, you should ignore the data.

Example

void
mainproc(void)
{
   OSMesgQueue  intMesgQueue;
   OSMesg       intMesgBuf[1];
   OSContStatus sdata[MAXCONTROLLERS];
   u8           pattern;

   osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
   osSetEventMesg(OS_EVENT_SI, &intMesgQueue, NULL);

   /* Initialize SI device */
   osContInit(&intMesgQueue, &pattern, &sdata[0]);    
   /* start reading SI device status and type */
   osContStartQuery(&intMesgQueue);
            %
            %
   /* Confirm the end of reading */
   osRecvMesg(&intMesgQueue, NULL, OS_MESG_BLOCK);
   /* Obtain SI device status and type */
   osContGetQuery(&sdata[0]);
}

See Also

osContInit, osContReset, osContStartReadData, osContGetReadData, osContSetCh, and osSetEventMesg

Revision History

1999/02/01 Completely revised
1999/04/30 Changed Format