Technical Note NW26

ARA GetUserPortGlobalsPtr Call

CONTENTS Introduction Conclusion References Downloadables

This Technical Note documents the Remote Access Manager (RAM) GetUserPortGlobalsPtr call. In order to make the RAM Status call on a machine that is setup to answer calls, you must first make the GetUserPortGlobalsPtr call to retrieve a pointer to the globals for the user port. [May 01 1993]

Introduction

The Apple Remote Access (ARA) 1.0 client software supports dial-out and answering capabilities through a single port called the "user" port (the modem or printer port on your Mac). This means that when you setup your machine to answer calls, you can answer only one call at a time on the user port. However, the underlying ARA architecture was designed so that in the future multiple ports may be supported (in a dial-in server for example).

When you dial out on your Mac and establish an ARA connection, ARA internally allocates the data structures for the user port - but not until a connection is actually made. This is why, for example, the Status call will return the -5833 ERR_PORTDOESNOTEXIST error on the originating machine if there is no active connection. Once a connection has been made on a machine that is the originator of the connection, the Status call should return no error, because the data structures for the port will have been created.

When you make the Status call on a machine that is setup to answer calls (the answer calls box is checked in the Remote Access Setup control panel), you will find that you always get the -5833 ERR_PORTDOESNOTEXIST error. The reason for this is that when ARA is in answer mode it needs to be able to uniquely identify each connection with a separate portGlobalsPtr, because in the future there may be support for more than one connection on a single machine. Therefore, on a machine that is setup to answer calls, you must first retrieve the portGlobalsPtr for the user port before the Status call can be made. This is accomplished with the GetUserPortGlobalsPtr call. This call makes use of the familiar TRemoteAccessParmHeader structure, which is defined in the AppleTalk Remote Access Developer's Toolkit:. The pointer to the port globals for the user port is returned in the portGlobalsPtr field upon completion of the call. Here are the data structures used by this call:

#define DControlParamHeader \
    QElem    *qLink;        /*next queue entry*/\
    short    qType;            /*queue type*/\
    short    ioTrap;        /*routine trap*/\
    Ptr    ioCmdAddr;            /*routine address*/\
    ProcPtr    ioCompletion;        /*completion routine*/\
    OSErr    ioResult;        /*result code*/\
    long    userData;        /*for use by the user */\
    short    unused;        /*unused field */\
    short    ioRefNum;        /*driver reference number*/\
    short    csCode;        /*Call command code*/

#define DExtendedParam \
    DControlParamHeader \
    Ptr    hReserved1; \
    Ptr    hReserved2; \
    Ptr    resultStrPtr; \
    Ptr    extendedType;        /* pointer to identifier string */


#define DRemoteAccessParmHeader    \
    DExtendedParam \
    short    extendedCode;        /* for use by extended call proc */\
    Ptr    portGlobalsPtr;    /* pointer to globals for this port (0=userport) */\


struct TRemoteAccessParmHeader
{
    DRemoteAccessParmHeader
};

The fields in the TRemoteAccessParmHeader structure used for the GetUserPortGlobalsPtr call to the Remote Access Manager are defined as follows:

-> 12 ioCompletion long pointer to completion routine

<- 16 ioResult word result code

-> 20 userData long for use by the user

-> 26 ioRefNum word driver reference number

-> 28 csCode word call command code

-> 40 extendedType long pointer to identifier string

-> 42 extendedCode word for use by extended call procedure

<--> 44 portGlobalsPtr long pointer to globals for this port (0 = return user port globals)

Here are the detailed descriptions of the parameter block fields used by this call:

ioCompletion pointer to completion routine.

ioResult result code returned by the call.

userData user data for use by the user.

ioRefNum driver reference number.

csCode command code, normally set to RAM_EXTENDED_CALL.

extendedType should be set to REMOTEACCESSNAME.

extendedCode set to 54 to indicate the GetUserPortGlobalsPtr call.

portGlobalsPtr returns a pointer to the globals for the port. On input pass 0 to indicate you want the user port globals.

The following result codes can be returned by the GetUserPortGlobalsPtr call:

noErr 0 no error.

ERR_PORTDOESNOTEXIST -5833 port does not exist.

ERR_PORTSHUTDOWN -5832 port is shutting down.

The following is an example of how you would use the GetUserPortGlobalsPtr call prior to making a Status call.

#include    "RemoteAccessInterface.h"

Str255                ResultStr;
Str255                UserName;
Str255                LastMessage;
Str255                ConnectedTo;


#define CmdRemoteAccess_GetUserPortGlobalsPtr 54

void DoStatus()
{
TRemoteAccessParamBlock    pb;

  /* Ask LTM driver for PortGlobals address */

  pb.HDR.csCode = RAM_EXTENDED_CALL;        /* extended call */
  pb.HDR.extendedType = (Ptr)REMOTEACCESSNAME;    /* to Netshare */
  pb.HDR.extendedCode = CmdRemoteAccess_GetUserPortGlobalsPtr; /* get user port
globals */
  pb.HDR.portGlobalsPtr = nil;             /* 0 = return user port globals */
  PBRemoteAccess( &pb, false );
  if (pb.HDR.ioResult != noErr)
    HandleError(pb.HDR.ioResult);
  else
  {

    /* Issue ARA Status Call */

    ResultStr[0] = 0;
    pb.STATUS.resultStrPtr = (Ptr)ResultStr;     /* put results here */
    pb.STATUS.extendedCode = CmdRemoteAccess_Status;     /* status command */
    pb.STATUS.userNamePtr = UserName;
    pb.STATUS.connectedToNamePtr = ConnectedTo;
    pb.STATUS.theLastStatusMsgPtr = LastMessage;
    pb.STATUS.statusUserNamePtr = 0;
    pb.STATUS.statusMsgSeqNum = 0;
    PBRemoteAccess( &pb, false );
    if (pb.STATUS.ioResult != noErr)
      HandleError(pb.STATUS.ioResult);

  }

Back to top

Conclusion

To make sure that the RAM Status call will work on machines that are setup to answer calls, you will need to first make the GetUserPortGlobalsPtr call so that the Remote Access Manager knows which port to return status information for.

Back to top

References

AppleTalk Remote Access Developer's Toolkit

Back to top

Downloadables

Back to top