VirtualBox

source: vbox/trunk/src/VBox/Main/include/ConsoleImpl.h@ 6812

Last change on this file since 6812 was 6464, checked in by vboxsync, 17 years ago

Simplified consoleInitReleaseLog a bit and fixed a little bug in the error handling.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 19.8 KB
Line 
1/** @file
2 *
3 * VBox Console COM Class definition
4 */
5
6/*
7 * Copyright (C) 2006-2007 innotek GmbH
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef ____H_CONSOLEIMPL
19#define ____H_CONSOLEIMPL
20
21#include "VirtualBoxBase.h"
22#include "ProgressImpl.h"
23
24class Guest;
25class Keyboard;
26class Mouse;
27class Display;
28class MachineDebugger;
29class OUSBDevice;
30class RemoteUSBDevice;
31class SharedFolder;
32class RemoteDisplayInfo;
33class AudioSniffer;
34class ConsoleVRDPServer;
35class VMMDev;
36
37#include <VBox/vrdpapi.h>
38#include <VBox/pdmdrv.h>
39
40struct VUSBIRHCONFIG;
41typedef struct VUSBIRHCONFIG *PVUSBIRHCONFIG;
42
43#include <list>
44
45// defines
46///////////////////////////////////////////////////////////////////////////////
47
48/**
49 * Checks the availability of the underlying VM device driver corresponding
50 * to the COM interface (IKeyboard, IMouse, IDisplay, etc.). When the driver is
51 * not available (NULL), sets error info and returns returns E_ACCESSDENIED.
52 * The translatable error message is defined in null context.
53 *
54 * Intended to used only within Console children (i,e. Keyboard, Mouse,
55 * Display, etc.).
56 *
57 * @param drv driver pointer to check (compare it with NULL)
58 */
59#define CHECK_CONSOLE_DRV(drv) \
60 do { \
61 if (!(drv)) \
62 return setError (E_ACCESSDENIED, tr ("The console is not powered up")); \
63 } while (0)
64
65/** @def VBOX_WITH_UNIXY_TAP_NETWORKING
66 * Unixy style TAP networking. This is defined in the Makefile since it's also
67 * used by NetworkAdapterImpl.h/cpp.
68 */
69#ifdef __DOXYGEN__
70# define VBOX_WITH_UNIXY_TAP_NETWORKING
71#endif
72
73// Console
74///////////////////////////////////////////////////////////////////////////////
75
76/** IConsole implementation class */
77class ATL_NO_VTABLE Console :
78 public VirtualBoxBaseWithChildrenNEXT,
79 public VirtualBoxSupportErrorInfoImpl <Console, IConsole>,
80 public VirtualBoxSupportTranslation <Console>,
81 public IConsole
82{
83 Q_OBJECT
84
85public:
86
87 DECLARE_NOT_AGGREGATABLE(Console)
88
89 DECLARE_PROTECT_FINAL_CONSTRUCT()
90
91 BEGIN_COM_MAP(Console)
92 COM_INTERFACE_ENTRY(ISupportErrorInfo)
93 COM_INTERFACE_ENTRY(IConsole)
94 END_COM_MAP()
95
96 NS_DECL_ISUPPORTS
97
98 Console();
99 ~Console();
100
101 HRESULT FinalConstruct();
102 void FinalRelease();
103
104 // public initializers/uninitializers for internal purposes only
105 HRESULT init (IMachine *aMachine, IInternalMachineControl *aControl);
106 void uninit();
107
108 // IConsole properties
109 STDMETHOD(COMGETTER(Machine)) (IMachine **aMachine);
110 STDMETHOD(COMGETTER(State)) (MachineState_T *aMachineState);
111 STDMETHOD(COMGETTER(Guest)) (IGuest **aGuest);
112 STDMETHOD(COMGETTER(Keyboard)) (IKeyboard **aKeyboard);
113 STDMETHOD(COMGETTER(Mouse)) (IMouse **aMouse);
114 STDMETHOD(COMGETTER(Display)) (IDisplay **aDisplay);
115 STDMETHOD(COMGETTER(Debugger)) (IMachineDebugger **aDebugger);
116 STDMETHOD(COMGETTER(USBDevices)) (IUSBDeviceCollection **aUSBDevices);
117 STDMETHOD(COMGETTER(RemoteUSBDevices)) (IHostUSBDeviceCollection **aRemoteUSBDevices);
118 STDMETHOD(COMGETTER(RemoteDisplayInfo)) (IRemoteDisplayInfo **aRemoteDisplayInfo);
119 STDMETHOD(COMGETTER(SharedFolders)) (ISharedFolderCollection **aSharedFolders);
120
121 // IConsole methods
122 STDMETHOD(PowerUp) (IProgress **aProgress);
123 STDMETHOD(PowerDown)();
124 STDMETHOD(Reset)();
125 STDMETHOD(Pause)();
126 STDMETHOD(Resume)();
127 STDMETHOD(PowerButton)();
128 STDMETHOD(SleepButton)();
129 STDMETHOD(SaveState) (IProgress **aProgress);
130 STDMETHOD(AdoptSavedState) (INPTR BSTR aSavedStateFile);
131 STDMETHOD(DiscardSavedState)();
132 STDMETHOD(GetDeviceActivity) (DeviceType_T aDeviceType,
133 DeviceActivity_T *aDeviceActivity);
134 STDMETHOD(AttachUSBDevice) (INPTR GUIDPARAM aId);
135 STDMETHOD(DetachUSBDevice) (INPTR GUIDPARAM aId, IUSBDevice **aDevice);
136 STDMETHOD(CreateSharedFolder) (INPTR BSTR aName, INPTR BSTR aHostPath, BOOL aWritable);
137 STDMETHOD(RemoveSharedFolder) (INPTR BSTR aName);
138 STDMETHOD(TakeSnapshot) (INPTR BSTR aName, INPTR BSTR aDescription,
139 IProgress **aProgress);
140 STDMETHOD(DiscardSnapshot) (INPTR GUIDPARAM aId, IProgress **aProgress);
141 STDMETHOD(DiscardCurrentState) (IProgress **aProgress);
142 STDMETHOD(DiscardCurrentSnapshotAndState) (IProgress **aProgress);
143 STDMETHOD(RegisterCallback) (IConsoleCallback *aCallback);
144 STDMETHOD(UnregisterCallback)(IConsoleCallback *aCallback);
145
146 // public methods for internal purposes only
147
148 /*
149 * Note: the following methods do not increase refcount. intended to be
150 * called only by the VM execution thread.
151 */
152
153 Guest *getGuest() { return mGuest; }
154 Keyboard *getKeyboard() { return mKeyboard; }
155 Mouse *getMouse() { return mMouse; }
156 Display *getDisplay() { return mDisplay; }
157 MachineDebugger *getMachineDebugger() { return mDebugger; }
158
159 const ComPtr <IMachine> &machine() { return mMachine; }
160
161 /** Method is called only from ConsoleVRDPServer */
162 IVRDPServer *getVRDPServer() { return mVRDPServer; }
163
164 ConsoleVRDPServer *consoleVRDPServer() { return mConsoleVRDPServer; }
165
166 HRESULT updateMachineState (MachineState_T aMachineState);
167
168 // events from IInternalSessionControl
169 HRESULT onDVDDriveChange();
170 HRESULT onFloppyDriveChange();
171 HRESULT onNetworkAdapterChange (INetworkAdapter *aNetworkAdapter);
172 HRESULT onSerialPortChange (ISerialPort *aSerialPort);
173 HRESULT onParallelPortChange (IParallelPort *aParallelPort);
174 HRESULT onVRDPServerChange();
175 HRESULT onUSBControllerChange();
176 HRESULT onSharedFolderChange (BOOL aGlobal);
177 HRESULT onUSBDeviceAttach (IUSBDevice *aDevice, IVirtualBoxErrorInfo *aError, ULONG aMaskedIfs);
178 HRESULT onUSBDeviceDetach (INPTR GUIDPARAM aId, IVirtualBoxErrorInfo *aError);
179
180 VMMDev *getVMMDev() { return mVMMDev; }
181 AudioSniffer *getAudioSniffer () { return mAudioSniffer; }
182
183 int VRDPClientLogon (uint32_t u32ClientId, const char *pszUser, const char *pszPassword, const char *pszDomain);
184 void VRDPClientConnect (uint32_t u32ClientId);
185 void VRDPClientDisconnect (uint32_t u32ClientId, uint32_t fu32Intercepted);
186 void VRDPInterceptAudio (uint32_t u32ClientId);
187 void VRDPInterceptUSB (uint32_t u32ClientId, void **ppvIntercept);
188 void VRDPInterceptClipboard (uint32_t u32ClientId);
189
190 void processRemoteUSBDevices (uint32_t u32ClientId, VRDPUSBDEVICEDESC *pDevList, uint32_t cbDevList);
191
192 // callback callers (partly; for some events console callbacks are notified
193 // directly from IInternalSessionControl event handlers declared above)
194 void onMousePointerShapeChange(bool fVisible, bool fAlpha,
195 uint32_t xHot, uint32_t yHot,
196 uint32_t width, uint32_t height,
197 void *pShape);
198 void onMouseCapabilityChange (BOOL supportsAbsolute, BOOL needsHostCursor);
199 void onStateChange (MachineState_T aMachineState);
200 void onAdditionsStateChange();
201 void onAdditionsOutdated();
202 void onKeyboardLedsChange (bool fNumLock, bool fCapsLock, bool fScrollLock);
203 void onUSBDeviceStateChange (IUSBDevice *aDevice, bool aAttached,
204 IVirtualBoxErrorInfo *aError);
205 void onRuntimeError (BOOL aFatal, INPTR BSTR aErrorID, INPTR BSTR aMessage);
206 HRESULT onShowWindow (BOOL aCheck, BOOL *aCanShow, ULONG64 *aWinId);
207
208 static const PDMDRVREG DrvStatusReg;
209
210 void reportAuthLibraryError (const char *filename, int rc)
211 {
212 setError (E_FAIL, tr("Could not load the external authentication library '%s' (%Vrc)"), filename, rc);
213 }
214
215 // for VirtualBoxSupportErrorInfoImpl
216 static const wchar_t *getComponentName() { return L"Console"; }
217
218private:
219
220 /**
221 * Base template for AutoVMCaller and SaveVMPtr. Template arguments
222 * have the same meaning as arguments of Console::addVMCaller().
223 */
224 template <bool taQuiet = false, bool taAllowNullVM = false>
225 class AutoVMCallerBase
226 {
227 public:
228 AutoVMCallerBase (Console *aThat) : mThat (aThat), mRC (S_OK)
229 {
230 Assert (aThat);
231 mRC = aThat->addVMCaller (taQuiet, taAllowNullVM);
232 }
233 ~AutoVMCallerBase()
234 {
235 if (SUCCEEDED (mRC))
236 mThat->releaseVMCaller();
237 }
238 /** Decreases the number of callers before the instance is destroyed. */
239 void release()
240 {
241 AssertReturnVoid (SUCCEEDED (mRC));
242 mThat->releaseVMCaller();
243 mRC = E_FAIL;
244 }
245 /** Restores the number of callers after by #release(). #rc() must be
246 * rechecked to ensure the operation succeeded. */
247 void add()
248 {
249 AssertReturnVoid (!SUCCEEDED (mRC));
250 mRC = mThat->addVMCaller (taQuiet, taAllowNullVM);
251 }
252 /** Returns the result of Console::addVMCaller() */
253 HRESULT rc() const { return mRC; }
254 /** Shortcut to SUCCEEDED (rc()) */
255 bool isOk() const { return SUCCEEDED (mRC); }
256 protected:
257 Console *mThat;
258 HRESULT mRC;
259 private:
260 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoVMCallerBase)
261 DECLARE_CLS_NEW_DELETE_NOOP (AutoVMCallerBase)
262 };
263
264 /**
265 * Helper class that protects sections of code using the mpVM pointer by
266 * automatically calling addVMCaller() on construction and
267 * releaseVMCaller() on destruction. Intended for Console methods dealing
268 * with mpVM. The usage pattern is:
269 * <code>
270 * AutoVMCaller autoVMCaller (this);
271 * CheckComRCReturnRC (autoVMCaller.rc());
272 * ...
273 * VMR3ReqCall (mpVM, ...
274 * </code>
275 *
276 * @sa SafeVMPtr, SafeVMPtrQuiet
277 */
278 typedef AutoVMCallerBase <false, false> AutoVMCaller;
279
280 /**
281 * Same as AutoVMCaller but doesn't set extended error info on failure.
282 */
283 typedef AutoVMCallerBase <true, false> AutoVMCallerQuiet;
284
285 /**
286 * Same as AutoVMCaller but allows a null VM pointer (to trigger an error
287 * instead of assertion).
288 */
289 typedef AutoVMCallerBase <false, true> AutoVMCallerWeak;
290
291 /**
292 * Same as AutoVMCaller but doesn't set extended error info on failure
293 * and allows a null VM pointer (to trigger an error instead of
294 * assertion).
295 */
296 typedef AutoVMCallerBase <true, true> AutoVMCallerQuietWeak;
297
298 /**
299 * Base template for SaveVMPtr and SaveVMPtrQuiet.
300 */
301 template <bool taQuiet = false>
302 class SafeVMPtrBase : public AutoVMCallerBase <taQuiet, true>
303 {
304 typedef AutoVMCallerBase <taQuiet, true> Base;
305 public:
306 SafeVMPtrBase (Console *aThat) : Base (aThat), mpVM (NULL)
307 {
308 if (SUCCEEDED (Base::mRC))
309 mpVM = aThat->mpVM;
310 }
311 /** Smart SaveVMPtr to PVM cast operator */
312 operator PVM() const { return mpVM; }
313 /** Direct PVM access for printf()-like functions */
314 PVM raw() const { return mpVM; }
315 private:
316 PVM mpVM;
317 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (SafeVMPtrBase)
318 DECLARE_CLS_NEW_DELETE_NOOP (SafeVMPtrBase)
319 };
320
321public:
322
323 /**
324 * Helper class that safely manages the Console::mpVM pointer
325 * by calling addVMCaller() on construction and releaseVMCaller() on
326 * destruction. Intended for Console children. The usage pattern is:
327 * <code>
328 * Console::SaveVMPtr pVM (mParent);
329 * CheckComRCReturnRC (pVM.rc());
330 * ...
331 * VMR3ReqCall (pVM, ...
332 * ...
333 * printf ("%p\n", pVM.raw());
334 * </code>
335 *
336 * @sa SafeVMPtrQuiet, AutoVMCaller
337 */
338 typedef SafeVMPtrBase <false> SafeVMPtr;
339
340 /**
341 * A deviation of SaveVMPtr that doesn't set the error info on failure.
342 * Intenede for pieces of code that don't need to return the VM access
343 * failure to the caller. The usage pattern is:
344 * <code>
345 * Console::SaveVMPtrQuiet pVM (mParent);
346 * if (pVM.rc())
347 * VMR3ReqCall (pVM, ...
348 * return S_OK;
349 * </code>
350 *
351 * @sa SafeVMPtr, AutoVMCaller
352 */
353 typedef SafeVMPtrBase <true> SafeVMPtrQuiet;
354
355 class SharedFolderData
356 {
357 public:
358 SharedFolderData() {}
359 SharedFolderData(Bstr aHostPath, BOOL aWritable)
360 : mHostPath (aHostPath)
361 , mWritable (aWritable) {}
362 SharedFolderData(const SharedFolderData& aThat)
363 : mHostPath (aThat.mHostPath)
364 , mWritable (aThat.mWritable) {}
365 Bstr mHostPath;
366 BOOL mWritable;
367 };
368 typedef std::map <Bstr, ComObjPtr <SharedFolder> > SharedFolderMap;
369 typedef std::map <Bstr, SharedFolderData> SharedFolderDataMap;
370
371private:
372
373 typedef std::list <ComObjPtr <OUSBDevice> > USBDeviceList;
374 typedef std::list <ComObjPtr <RemoteUSBDevice> > RemoteUSBDeviceList;
375
376 HRESULT addVMCaller (bool aQuiet = false, bool aAllowNullVM = false);
377 void releaseVMCaller();
378
379 HRESULT consoleInitReleaseLog (const ComPtr <IMachine> aMachine);
380
381 HRESULT powerDown();
382
383 HRESULT callTapSetupApplication(bool isStatic, RTFILE tapFD, Bstr &tapDevice,
384 Bstr &tapSetupApplication);
385 HRESULT attachToHostInterface(INetworkAdapter *networkAdapter);
386 HRESULT detachFromHostInterface(INetworkAdapter *networkAdapter);
387 HRESULT powerDownHostInterfaces();
388
389 HRESULT setMachineState (MachineState_T aMachineState, bool aUpdateServer = true);
390 HRESULT setMachineStateLocally (MachineState_T aMachineState)
391 {
392 return setMachineState (aMachineState, false /* aUpdateServer */);
393 }
394
395 HRESULT findSharedFolder (const BSTR aName,
396 ComObjPtr <SharedFolder> &aSharedFolder,
397 bool aSetError = false);
398
399 HRESULT fetchSharedFolders (BOOL aGlobal);
400 bool findOtherSharedFolder (INPTR BSTR aName,
401 SharedFolderDataMap::const_iterator &aIt);
402
403 HRESULT createSharedFolder (INPTR BSTR aName, SharedFolderData aData);
404 HRESULT removeSharedFolder (INPTR BSTR aName);
405
406 static DECLCALLBACK(int) configConstructor(PVM pVM, void *pvConsole);
407 static DECLCALLBACK(void) vmstateChangeCallback(PVM aVM, VMSTATE aState,
408 VMSTATE aOldState, void *aUser);
409 HRESULT doDriveChange (const char *pszDevice, unsigned uInstance,
410 unsigned uLun, DriveState_T eState,
411 DriveState_T *peState, const char *pszPath,
412 bool fPassthrough);
413 static DECLCALLBACK(int) changeDrive (Console *pThis, const char *pszDevice,
414 unsigned uInstance, unsigned uLun,
415 DriveState_T eState, DriveState_T *peState,
416 const char *pszPath, bool fPassthrough);
417
418#ifdef VBOX_WITH_USB
419 HRESULT attachUSBDevice (IUSBDevice *aHostDevice, ULONG aMaskedIfs);
420 HRESULT detachUSBDevice (USBDeviceList::iterator &aIt);
421
422 static DECLCALLBACK(int)
423 usbAttachCallback (Console *that, IUSBDevice *aHostDevice, PCRTUUID aUuid,
424 bool aRemote, const char *aAddress, ULONG aMaskedIfs);
425 static DECLCALLBACK(int)
426 usbDetachCallback (Console *that, USBDeviceList::iterator *aIt, PCRTUUID aUuid);
427#endif
428
429 static DECLCALLBACK (int)
430 stateProgressCallback (PVM pVM, unsigned uPercent, void *pvUser);
431
432 static DECLCALLBACK(void)
433 setVMErrorCallback (PVM pVM, void *pvUser, int rc, RT_SRC_POS_DECL,
434 const char *pszFormat, va_list args);
435
436 static DECLCALLBACK(void)
437 setVMRuntimeErrorCallback (PVM pVM, void *pvUser, bool fFatal,
438 const char *pszErrorID,
439 const char *pszFormat, va_list args);
440
441 HRESULT captureUSBDevices (PVM pVM);
442 void detachAllUSBDevices (bool aDone);
443
444 static DECLCALLBACK (int) powerUpThread (RTTHREAD Thread, void *pvUser);
445 static DECLCALLBACK (int) saveStateThread (RTTHREAD Thread, void *pvUser);
446 static DECLCALLBACK (int) powerDownThread (RTTHREAD Thread, void *pvUser);
447
448 static DECLCALLBACK(void *) drvStatus_QueryInterface(PPDMIBASE pInterface, PDMINTERFACE enmInterface);
449 static DECLCALLBACK(void) drvStatus_UnitChanged(PPDMILEDCONNECTORS pInterface, unsigned iLUN);
450 static DECLCALLBACK(void) drvStatus_Destruct(PPDMDRVINS pDrvIns);
451 static DECLCALLBACK(int) drvStatus_Construct(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
452
453 int mcAudioRefs;
454 volatile uint32_t mcVRDPClients;
455
456 static const char *sSSMConsoleUnit;
457 static uint32_t sSSMConsoleVer;
458
459 HRESULT loadDataFromSavedState();
460
461 static DECLCALLBACK(void) saveStateFileExec (PSSMHANDLE pSSM, void *pvUser);
462 static DECLCALLBACK(int) loadStateFileExec (PSSMHANDLE pSSM, void *pvUser, uint32_t u32Version);
463
464 bool mSavedStateDataLoaded : 1;
465
466 const ComPtr <IMachine> mMachine;
467 const ComPtr <IInternalMachineControl> mControl;
468
469 const ComPtr <IVRDPServer> mVRDPServer;
470 const ComPtr <IDVDDrive> mDVDDrive;
471 const ComPtr <IFloppyDrive> mFloppyDrive;
472
473 ConsoleVRDPServer * const mConsoleVRDPServer;
474
475 const ComObjPtr <Guest> mGuest;
476 const ComObjPtr <Keyboard> mKeyboard;
477 const ComObjPtr <Mouse> mMouse;
478 const ComObjPtr <Display> mDisplay;
479 const ComObjPtr <MachineDebugger> mDebugger;
480 const ComObjPtr <RemoteDisplayInfo> mRemoteDisplayInfo;
481
482 USBDeviceList mUSBDevices;
483 RemoteUSBDeviceList mRemoteUSBDevices;
484
485 SharedFolderMap mSharedFolders;
486 SharedFolderDataMap mMachineSharedFolders;
487 SharedFolderDataMap mGlobalSharedFolders;
488
489 /** The VM instance handle. */
490 PVM mpVM;
491 /** Holds the number of "readonly" mpVM callers (users) */
492 uint32_t mVMCallers;
493 /** Semaphore posted when the number of mpVM callers drops to zero */
494 RTSEMEVENT mVMZeroCallersSem;
495 /** true when Console has entered the mpVM destruction phase */
496 bool mVMDestroying : 1;
497
498 /** The current DVD drive state in the VM.
499 * This does not have to match the state maintained in the DVD. */
500 DriveState_T meDVDState;
501 /** The current Floppy drive state in the VM.
502 * This does not have to match the state maintained in the Floppy. */
503 DriveState_T meFloppyState;
504
505 VMMDev * const mVMMDev;
506 AudioSniffer * const mAudioSniffer;
507
508 PPDMLED mapFDLeds[2];
509 PPDMLED mapIDELeds[4];
510 PPDMLED mapNetworkLeds[8];
511 PPDMLED mapSharedFolderLed;
512 PPDMLED mapUSBLed;
513#ifdef VBOX_WITH_UNIXY_TAP_NETWORKING
514 Utf8Str maTAPDeviceName[8];
515 RTFILE maTapFD[8];
516#endif
517
518 bool mVMStateChangeCallbackDisabled;
519
520 /* Local machine state value */
521 MachineState_T mMachineState;
522
523 typedef std::list <ComPtr <IConsoleCallback> > CallbackList;
524 CallbackList mCallbacks;
525
526 struct
527 {
528 /** OnMousePointerShapeChange() cache */
529 struct
530 {
531 bool valid;
532 bool visible;
533 bool alpha;
534 uint32_t xHot;
535 uint32_t yHot;
536 uint32_t width;
537 uint32_t height;
538 BYTE *shape;
539 size_t shapeSize;
540 }
541 mpsc;
542
543 /** OnMouseCapabilityChange() cache */
544 struct
545 {
546 bool valid;
547 BOOL supportsAbsolute;
548 BOOL needsHostCursor;
549 }
550 mcc;
551
552 /** OnKeyboardLedsChange() cache */
553 struct
554 {
555 bool valid;
556 bool numLock;
557 bool capsLock;
558 bool scrollLock;
559 }
560 klc;
561 }
562 mCallbackData;
563
564 friend struct VMTask;
565};
566
567#endif // ____H_CONSOLEIMPL
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette