Retired Document
Important: This sample code may not represent best practices for current development. The project may use deprecated symbols and illustrate technologies and techniques that are no longer recommended.
MIB-Libraries/MoreInterfaceLib/RemoteAccessInterface.h
/* |
File: RemoteAccessInterface.h |
Contains: Interface for making remote access calls. |
Written by: Quinn (conversion to Universal Interfaces 3.2 format) |
Copyright: Copyright (c) 1991-2001 by Apple Computer, Inc., All Rights Reserved. |
Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Computer, Inc. |
("Apple") in consideration of your agreement to the following terms, and your |
use, installation, modification or redistribution of this Apple software |
constitutes acceptance of these terms. If you do not agree with these terms, |
please do not use, install, modify or redistribute this Apple software. |
In consideration of your agreement to abide by the following terms, and subject |
to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs |
copyrights in this original Apple software (the "Apple Software"), to use, |
reproduce, modify and redistribute the Apple Software, with or without |
modifications, in source and/or binary forms; provided that if you redistribute |
the Apple Software in its entirety and without modifications, you must retain |
this notice and the following text and disclaimers in all such redistributions of |
the Apple Software. Neither the name, trademarks, service marks or logos of |
Apple Computer, Inc. may be used to endorse or promote products derived from the |
Apple Software without specific prior written permission from Apple. Except as |
expressly stated in this notice, no other rights or licenses, express or implied, |
are granted by Apple herein, including but not limited to any patent rights that |
may be infringed by your derivative works or by other works in which the Apple |
Software may be incorporated. |
The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO |
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED |
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN |
COMBINATION WITH YOUR PRODUCTS. |
IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR |
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE |
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION |
OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT |
(INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN |
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
Change History (most recent first): |
$Log: RemoteAccessInterface.h,v $ |
Revision 1.4 2002/11/08 23:32:32 |
Convert nil to NULL. |
Revision 1.3 2001/11/07 15:57:27 |
Tidy up headers, add CVS logs, update copyright. |
<2> 22/11/00 Quinn Switch to "MacTypes.h". |
<1> 22/4/99 Quinn First checked in. |
*/ |
#ifndef __REMOTEACCESSINTERFACE__ |
#define __REMOTEACCESSINTERFACE__ |
#ifndef __TYPES__ |
#include <MacTypes.h> |
#endif |
#ifndef __FILES__ |
#include <Files.h> |
#endif |
#ifndef __APPLETALK__ |
#include <AppleTalk.h> |
#endif |
#if PRAGMA_ONCE |
#pragma once |
#endif |
#ifdef __cplusplus |
extern "C" { |
#endif |
#if PRAGMA_IMPORT |
#pragma import on |
#endif |
#if PRAGMA_STRUCT_ALIGN |
#pragma options align=mac68k |
#elif PRAGMA_STRUCT_PACKPUSH |
#pragma pack(push, 2) |
#elif PRAGMA_STRUCT_PACK |
#pragma pack(2) |
#endif |
/* **** These callbacks are yet to be Universal Interfaced... **** */ |
typedef pascal void (*UserStatusProcPtr)(UInt8 *, UInt8 *); |
typedef pascal long (*PacketFilterProcPtr)(UInt8 *, UInt32, UInt32, UInt8 *, UInt32); |
typedef pascal void (*RemmaperProcPtr)(UInt32, UInt32, UInt32, UInt8 *, UInt8 *); |
typedef pascal void (*CallBackHookProcPtr)(UInt8 *, UInt32); |
typedef pascal void (*CallBackCompHookProcPtr)(UInt8 *); |
typedef pascal UInt32 (*NetValidProcPtr)(UInt8 *,AddrBlock); |
#define REMOTEACCESSNAME "\pRemote Access" |
#define REMOTEACCESSID 'strm' // *** NOTE: "Network Extension" uses this id for its _Gestalt call |
#define gestaltRemoteAccessAttr REMOTEACCESSID |
#define gestaltRemoteAccessExists 0 |
#define gestaltRemoteAccessCallOnly 1 /* Remote Access Client */ |
#define gestaltRemoteAccessMPServer 2 /* Remote Access multi-port server */ |
#define gestaltRemoteAccessVers2 3 /* ARA 2.0 features are available */ |
#define MAXSTATUSMSGSIZE 256 |
#define USERNAMESIZE 34 |
#define PASSWORDSIZE 8 |
#define PASSWORDBUFSIZE PASSWORDSIZE+1 |
#define TIME_UNLIMITED 0xffffffff /* indicates unlimited time allowed on connection */ |
#define ctlir_getConnectInfo 0x01 /* will get connect info if address is remote */ |
#define ctlir_disposeConnectInfo 0x02 /* will dispose info in connectInfoPtr properly */ |
/* control codes |
*/ |
#define RAM_EXTENDED_CALL 23 /* make an extended call (use TRemoteAccessParamBlock) */ |
/* extended codes (must have control code set to RAM_EXTENDED_CALL) |
*/ |
/* the first group of calls can be issued without doing a load */ |
#define CmdRemoteAccess_Load 1 /* loads main section of remote access */ |
#define CmdRemoteAccess_Unload 2 /* unloads main section */ |
#define CmdRemoteAccess_PassWordMunger 6 /* create a munged password */ |
#define CmdRemoteAccess_GetCodeHooks 7 /* get code hooks */ |
/* calls that will not work until CmdRemoteAccess_Load has been done */ |
#define CmdRemoteAccess_DoConnect 40 /* main thread only */ |
#define CmdRemoteAccess_Disconnect 42 /* disconnect */ |
#define CmdRemoteAccess_Status 45 /* get status information */ |
#define CmdRemoteAccess_IsAddressRemote 53 /* main thread only when getting/setting connect pb info */ |
/* Remote Access errors */ |
#define ERR_BASE -5800 |
#define ERR_NOTCONNECTED (ERR_BASE-0) |
#define ERR_CONNECTIONABORTED (ERR_BASE-1) |
#define ERR_ALREADYCONNECTED (ERR_BASE-2) |
#define ERR_COMMANDALREADYINPROGRESS (ERR_BASE-3) |
#define ERR_BADVERSION (ERR_BASE-4) |
#define ERR_INSHUTDOWN (ERR_BASE-5) |
#define ERR_CONNECTIONABORTING (ERR_BASE-6) |
#define ERR_ALREADYENABLED (ERR_BASE-7) |
#define ERR_ZONEBUFBADSIZE (ERR_BASE-8) |
#define ERR_CONNECTTIMEDOUT (ERR_BASE-9) |
#define ERR_CONNECTUSERTIMEDOUT (ERR_BASE-10) |
#define ERR_BADPARAMETER (ERR_BASE-11) |
#define ERR_NOMULTINODE (ERR_BASE-12) |
#define ERR_ATALKNOTACTIVE (ERR_BASE-13) |
#define ERR_NOCALLBACKSUPPORT (ERR_BASE-14) |
#define ERR_NOTOPENEDBYTHISPB (ERR_BASE-15) |
#define ERR_NOGLOBALS (ERR_BASE-16) |
#define ERR_NOSMARTBUFFER (ERR_BASE-17) |
#define ERR_BADATALKVERS (ERR_BASE-18) |
#define ERR_VLD8_CONNECT 0 |
#define ERR_VLD8_CALLBACK (ERR_BASE-19) |
#define ERR_VLD8_BADVERSION (ERR_BASE-20) |
#define ERR_VLD8_BADUSER (ERR_BASE-21) |
#define ERR_VLD8_BADPASSWORD (ERR_BASE-22) |
#define ERR_VLD8_BADLINK (ERR_BASE-23) |
#define ERR_VLD8_NOCALLBACKALLOWED (ERR_BASE-24) |
#define ERR_VLD8_ALLCBSERVERSBUSY (ERR_BASE-25) |
#define ERR_VLD8_GUESTNOTALLOWED (ERR_BASE-26) |
#define ERR_VLD8_SERVERISIMPOSTER (ERR_BASE-27) |
#define ERR_VLD8_LOGINNOTENABLED (ERR_BASE-28) |
#define ERR_REMOTEPORTALREADYEXISTS (ERR_BASE-29) |
#define ERR_OPENNOTALLOWED (ERR_BASE-30) |
#define ERR_NOUSERSANDGROUPS (ERR_BASE-31) |
#define ERR_PORTSHUTDOWN (ERR_BASE-32) |
#define ERR_PORTDOESNOTEXIST (ERR_BASE-33) |
#define ERR_PWNEEDEDFORENABLE (ERR_BASE-34) |
#define ERR_DAMAGED (ERR_BASE-35) |
#define ERR_NETCONFIGCHANGED (ERR_BASE-36) |
/* 2.0 and above onlyÉ */ |
#define ERR_NOSUPPORT_ATREMOTE (ERR_BASE-37) |
#define ERR_CONFLICTING_REQUEST (ERR_BASE-38) |
#define ERR_VLD8_INVALIDAUTHMETHOD (ERR_BASE-39) |
#define ERR_VLD8_CONTINUE (ERR_BASE-40) |
#define ERR_PWCHANGECANCEL (ERR_BASE-41) |
#define ERR_VLD8_MANUALPASSWORDREQUIRED (ERR_BASE-50) |
#define ERR_END ERR_VLD8_MANUALPASSWORDREQUIRED /* must be last error */ |
#define kTemplateVers 1 /* current version understood by remote access for the connect template */ |
/* forward defs */ |
typedef union TRemoteAccessParamBlock TRemoteAccessParamBlock; |
typedef TRemoteAccessParamBlock *TPRemoteAccessParamBlock; |
/* network transition */ |
struct TNetworkTransition |
{ |
unsigned char *privateVars; /* pointer used internally by Remote Access */ |
NetValidProcPtr netValidProc; /* pointer to the network valid procedure */ |
Boolean newConnectivity; /* set to true if new connectivity, false if loss of connectivity */ |
}; |
typedef struct TNetworkTransition TNetworkTransition; |
typedef TNetworkTransition *TPNetworkTransition; |
#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 |
}; |
typedef struct TRemoteAccessParmHeader TRemoteAccessParmHeader; |
struct TRAConnectInfoTemplate |
{ |
unsigned long version; /* version of this format */ |
unsigned long ltType; /* Link Tool type */ |
long addressInfoLength; /* length of the address information */ |
Ptr addressInfoPtr; /* pointer to connect address info */ |
long ltSpecificTemplateLength;/* length of the ltspecific information */ |
Ptr ltSpecificTemplatePtr; /* pointer to link tool specific params */ |
unsigned char passWord[PASSWORDBUFSIZE]; /* user password */ |
unsigned char userName[USERNAMESIZE]; /* user name */ |
unsigned long connectReminderTimer; /* value for connection reminder in seconds */ |
unsigned long connectOKWaitTimer; /* how long to wait for OK on reminder timer */ |
Boolean guestLogin; /* try to log in as a guest */ |
Boolean passwordSaved; /* set if password is saved */ |
Boolean guaranteedAccess; /* flag to guarantee access to servers internet */ |
}; |
typedef struct TRAConnectInfoTemplate TRAConnectInfoTemplate; |
typedef TRAConnectInfoTemplate *TPRAConnectInfoTemplate; |
/* connect option flags |
*/ |
#define kNSCanInteract 0x00000001 // User interaction (password prompt) is OK |
#define kNSShowStatus 0x00000002 // show the status of the connect or disconnect call |
#define kNSConnectDocument 0x00000004 // connect using the specified document |
#define kNSPassWordSet 0x00000010 // use the specified password field when connecting by document |
// 2.0 and aboveÉ |
#define kNS2SavvyFlags 0x40000000 // Set to use the next 2 flags below for only ARA 2.0 aware applications. |
#define kNSAR2Connection 0x00000020 // connecting to a 2.0 server. |
#define kNSNotifyWhileConnected 0x00000040 // display cute notification icon while connected. |
struct TRemoteAccessConnectParam |
{ |
DRemoteAccessParmHeader |
TRAConnectInfoTemplate connectInfo; /* The connection infomation template */ |
unsigned long optionFlags; // bit mapped connect option flags |
FSSpec fileInfo; // file info for connect document |
}; |
typedef struct TRemoteAccessConnectParam TRemoteAccessConnectParam; |
#define kNumWarnEntriesMax 5 /* number of entries in warn array */ |
struct TRemoteAccessDisconnectParam |
{ |
DRemoteAccessParmHeader |
unsigned long disconnectin; /* server mode: disconnect in # of seconds */ |
TPRemoteAccessParamBlock abortOnlyThisPB; /* only abort a connection opened by this pb */ |
unsigned long warnArr[kNumWarnEntriesMax]; /* set warn times here in seconds (zero all if no warnings) */ |
unsigned long optionFlags; /* bit mapped connect option flags */ |
}; |
typedef struct TRemoteAccessDisconnectParam TRemoteAccessDisconnectParam; |
/* bits passed back in status call */ |
#define CctlConnected 0x00000001 /* set when connected */ |
#define CctlAnswerEnable 0x00000004 /* set when we are set to answer calls */ |
#define CctlServerMode 0x00000008 /* set for server mode, clear for remote mode */ |
#define CctlConnectionAborting 0x00000010 /* connection is being torn down */ |
#define CctlConnectInProg 0x00000020 /* set when connection in progress or fully connected */ |
#define CctlDisconnectInStarted 0x00008000 /* somebody has started a disconnectIn */ |
#define CctlGuestMode 0x00080000 /* set if this port is logged on with guest access */ |
#define ctlAR2Connection 0x02000000 /* set when this connection is to a 2.0 server */ |
#define ctlNotifyWhileConnected 0x04000000 /* set when the user wants to be reminded while connected */ |
#define ctlConnectedToMPS 0x08000000 /* set when client is connected to a multi-port server */ |
#define CctlMultiNodeReady 0x80000000 /* shows if we currently have a multinode address */ |
struct TRemoteAccessStatusParam |
{ |
DRemoteAccessParmHeader |
unsigned long statusBits; /* bits for current status */ |
unsigned long timeConnected; /* number of seconds we have been connected */ |
unsigned long timeLeft; /* number of seconds remaining in connection (0xffffffff infinite) */ |
unsigned char *userNamePtr; /* returns user name, expects pointer to buffer of USERNAMESIZE if non NULL */ |
unsigned char *connectedToNamePtr; /* returns name of where we connected to, expects pointer to buffer of USERNAMESIZE if non NULL */ |
TPRemoteAccessParamBlock connectedByParamPtr; /* a pointer to the parameter block "initiating" the connection if we are connected */ |
TPRemoteAccessParamBlock statusConnectedByParamPtr; /* a pointer to the parameter block "initiating" the connection when status was posted */ |
unsigned char *theLastStatusMsgPtr; /* expects pointer to buffer of size MAXSTATUSMSGSIZE */ |
unsigned char *statusUserNamePtr; /* pointer to buffer of size USERNAMESIZE */ |
long statuslttype; /* link tool type */ |
long statusmsgOptionFlags; /* classification of message type */ |
long statusMsgNum; /* specific message number */ |
long statusMsgSeqNum; /* pass in zero if always want status, otherwise use last value, if status is new, new number is returned */ |
unsigned long userSignature; /* signature of port creator */ |
unsigned long userRefCon; /* refcon of port creator */ |
}; |
typedef struct TRemoteAccessStatusParam TRemoteAccessStatusParam; |
struct TRemoteAccessIsRemoteParms |
{ |
DRemoteAccessParmHeader |
long theAddress; /* address that is to be checked */ |
unsigned long optionFlags; /* Set to ctlir_getConnectInfo or ctlir_disposeConnectInfo, if zero only checks address */ |
Boolean locationIsRemoteFlag; /* returns true if address is remote */ |
long ConnectInfoLength; /* length of the following data */ |
TPRAConnectInfoTemplate connectInfoPtr; /* The connection information template pointer */ |
}; |
typedef struct TRemoteAccessIsRemoteParms TRemoteAccessIsRemoteParms; |
struct TRemoteAccessPasswordMunger |
{ |
DRemoteAccessParmHeader |
unsigned char *userNamePtr; /* pointer to username string */ |
unsigned char *passWordPtr; /* user password */ |
unsigned short reserved; /* must set to zero */ |
}; |
typedef struct TRemoteAccessPasswordMunger TRemoteAccessPasswordMunger; |
struct TRemoteAccessGetCodeHooks |
{ |
DRemoteAccessParmHeader |
RemmaperProcPtr remapperProc; /* quick vector to remapper code */ |
}; |
typedef struct TRemoteAccessGetCodeHooks TRemoteAccessGetCodeHooks; |
/* this is the union of all the different command types */ |
union TRemoteAccessParamBlock |
{ |
TRemoteAccessParmHeader HDR; /* header pb */ |
TRemoteAccessParmHeader LOAD; /* load pb */ |
TRemoteAccessParmHeader UNLOAD; /* unload pb */ |
TRemoteAccessConnectParam CONNECT; /* connect pb */ |
TRemoteAccessDisconnectParam DISCONNECT; /* disconnect pb */ |
TRemoteAccessStatusParam STATUS; /* get current status */ |
TRemoteAccessIsRemoteParms ISREMOTE; /* used to check network address location */ |
TRemoteAccessPasswordMunger MUNGEPW; /* run password through munger */ |
TRemoteAccessGetCodeHooks CODEHOOKS; /* get internal code hooks */ |
unsigned char filler[256]; /* set the minimum size of this parameter block */ |
}; |
EXTERN_API ( OSErr ) PBRemoteAccess(TPRemoteAccessParamBlock paramBlock, Boolean async) |
TWOWORDINLINE(0x7000,0xAA5B); |
#if PRAGMA_STRUCT_ALIGN |
#pragma options align=reset |
#elif PRAGMA_STRUCT_PACKPUSH |
#pragma pack(pop) |
#elif PRAGMA_STRUCT_PACK |
#pragma pack() |
#endif |
#ifdef PRAGMA_IMPORT_OFF |
#pragma import off |
#elif PRAGMA_IMPORT |
#pragma import reset |
#endif |
#ifdef __cplusplus |
} |
#endif |
#endif /* __REMOTEACCESSINTERFACE__ */ |
Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-10-27