osContInit

#include <ultra64.h>  /* os.h */
s32 osContInit(OSMesgQueue *mq, u8 *bitpattern, OSContStatus *status);

Explanation
The osContInit function initializes the SI settings and checks the status and type of SI device.

This function must be called before you call any functions to be used for initialization that are unique to each SI device. By doing this, the system checks the connection status of the SI device. If the Plf is busy, the timer waits until it is available for use by the SI device. This is because PIf is used to establish connection between the game pack right after N64 launches. While it is in use, PIf cannot be used.

The osContInit must be called before all the SI device functions are called. However, it should be called only once after the program launches or a reset is performed. It is not necessary to call this functin more than twice. This function does nothing after the second call. Therefore, if the status and type of SI device need to be checked after the first osContInit call, please use the osContStartQuery() function and osContGetQuery()

The osContInit function returns to a bitmap pattern specified by bitpattern the result which controller port the direct SI device is connected to. There are two types of SI devices; the one SI device can be identified as "Direct SI" device which can be connected with joybus or external joybus to establish direct connection with PIf, the other type of SI device can be identified as "Pack SI" device which is used to connect to joyport of a controller. Bit 0, 1, 2, 3 of a bitpattern corespond to controller port 0, 1, 2, 3, respectively. Direct SI device is inserted to the controller port 0 if the bit 0 of a bitpattern is set to 1. Also, the osContInit function examines the status of joyport and returns the result to "status" when Controller is connected. The area specifed by status must be large enough to hold the number of OSContStatus structures specified by MAXCONTROLLERS which store the status for each device inserted to the controller port.

typedef struct {
       	u16	type;  	/* Controller type */
        u8  	status;	/* Controller Pak status */
       	u8    	errno;	/* Error from SI device */
}OSContStatus;

The message queue, mq, is the initialized message queue linked to OS_EVENT_SI. Please see the osSetEventMesg() function to learn how to create this link. Since "mq" is used inside the function to wait for messages, the application does not need to use "mq" to wait for an end-of-function message.

0 is returned if initialization is successful, and -1 is returned if it fails to transfer data while SI is in use. It is rarely seen that -1 is returned.

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.

When it is recognized that the Controller socket was not connected, or communication error occurs in a controller port(bitpattern's bit is zero, or status->errno is not zero), the Controller's status type and status value become invalid. You need to make sure the Controller is connected properly by looking at the bit pattern first before examining the Controller type and status.

Although it used to be performed in this function with OS 2.0e or previous versions, resetting a controller cannot be accomplished in this function with OS 2.0f or later. Normally it is not necessary to reset a controller, however it can be accomplished to use osContReset()

The following sample shows how to use osContInit function within a program. The function checks each controller port to report which type of direct SI device is inserted.

Example

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

  osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
  osSetEventMesg(OS_EVENT_SI, &intMesgQueue, NULL);
  osContInit(&intMesgQueue, &pattern, &sdata[0]);

  for(i = 0; i < MAXCONTROLLERS; i++){
    if(((pattern >> i) & 1) && (sdata[i].errno == 0)){
      if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_NORMAL){
        osSyncPrintf("Standard Controller\n");
      }
      else if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_MOUSE){
        osSyncPrintf("Mouse\n");
      }
      else if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_VOICE){
        osSyncPrintf("Voiced Recognition System\n");
      }
      else{
        osSyncPrintf("Other Devices\n");
      }
    }else{
      osSyncPrintf("Nothing is inserted in this port\n");
    }
  }
}