source/modules/juce_core/threads/juce_Process.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /** Represents the current executable's process.
  28
  29     This contains methods for controlling the current application at the
  30     process-level.
  31
  32     @see Thread, JUCEApplicationBase
  33
  34     @tags{Core}
  35 */
  36 class JUCE_API  Process
  37 {
  38 public:
  39     //==============================================================================
  40     enum ProcessPriority
  41     {
  42         LowPriority         = 0,
  43         NormalPriority      = 1,
  44         HighPriority        = 2,
  45         RealtimePriority    = 3
  46     };
  47
  48     /** Changes the current process's priority.
  49
  50         @param priority     the process priority, where
  51                             0=low, 1=normal, 2=high, 3=realtime
  52     */
  53     static void JUCE_CALLTYPE setPriority (const ProcessPriority priority);
  54
  55     /** Kills the current process immediately.
  56
  57         This is an emergency process terminator that kills the application
  58         immediately - it's intended only for use only when something goes
  59         horribly wrong.
  60
  61         @see JUCEApplicationBase::quit
  62     */
  63     static void JUCE_CALLTYPE terminate();
  64
  65     //==============================================================================
  66     /** Returns true if this application process is the one that the user is
  67         currently using.
  68     */
  69     static bool JUCE_CALLTYPE isForegroundProcess();
  70
  71     /** Attempts to make the current process the active one.
  72         (This is not possible on some platforms).
  73     */
  74     static void JUCE_CALLTYPE makeForegroundProcess();
  75
  76     /** Hides the application (on an OS that supports this, e.g. OSX, iOS, Android) */
  77     static void JUCE_CALLTYPE hide();
  78
  79     //==============================================================================
  80     /** Raises the current process's privilege level.
  81
  82         Does nothing if this isn't supported by the current OS, or if process
  83         privilege level is fixed.
  84     */
  85     static void JUCE_CALLTYPE raisePrivilege();
  86
  87     /** Lowers the current process's privilege level.
  88
  89         Does nothing if this isn't supported by the current OS, or if process
  90         privilege level is fixed.
  91     */
  92     static void JUCE_CALLTYPE lowerPrivilege();
  93
  94     //==============================================================================
  95     /** Returns true if this process is being hosted by a debugger. */
  96     static bool JUCE_CALLTYPE isRunningUnderDebugger() noexcept;
  97
  98
  99     //==============================================================================
 100     /** Tries to launch the OS's default reader application for a given file or URL. */
 101     static bool JUCE_CALLTYPE openDocument (const String& documentURL, const String& parameters);
 102
 103     /** Tries to launch the OS's default email application to let the user create a message. */
 104     static bool JUCE_CALLTYPE openEmailWithAttachments (const String& targetEmailAddress,
 105                                                         const String& emailSubject,
 106                                                         const String& bodyText,
 107                                                         const StringArray& filesToAttach);
 108
 109     //==============================================================================
 110    #if JUCE_WINDOWS || DOXYGEN
 111     /** WINDOWS ONLY - This returns the HINSTANCE of the current module.
 112
 113         The return type is a void* to avoid being dependent on windows.h - just cast
 114         it to a HINSTANCE to use it.
 115
 116         In a normal JUCE application, this will be automatically set to the module
 117         handle of the executable.
 118
 119         If you've built a DLL and plan to use any JUCE messaging or windowing classes,
 120         you'll need to make sure you call the setCurrentModuleInstanceHandle()
 121         to provide the correct module handle in your DllMain() function, because
 122         the system relies on the correct instance handle when opening windows.
 123     */
 124     static void* JUCE_CALLTYPE getCurrentModuleInstanceHandle() noexcept;
 125
 126     /** WINDOWS ONLY - Sets a new module handle to be used by the library.
 127
 128         The parameter type is a void* to avoid being dependent on windows.h, but it actually
 129         expects a HINSTANCE value.
 130
 131         @see getCurrentModuleInstanceHandle()
 132     */
 133     static void JUCE_CALLTYPE setCurrentModuleInstanceHandle (void* newHandle) noexcept;
 134    #endif
 135
 136     //==============================================================================
 137    #if (JUCE_MAC && JUCE_MODULE_AVAILABLE_juce_gui_basics) || DOXYGEN
 138     /** OSX ONLY - Shows or hides the OSX dock icon for this app. */
 139     static void setDockIconVisible (bool isVisible);
 140    #endif
 141
 142     //==============================================================================
 143    #if JUCE_MAC || JUCE_LINUX || JUCE_BSD || DOXYGEN
 144     /** UNIX ONLY - Attempts to use setrlimit to change the maximum number of file
 145         handles that the app can open. Pass 0 or less as the parameter to mean
 146         'infinite'. Returns true if it succeeds.
 147     */
 148     static bool setMaxNumberOfFileHandles (int maxNumberOfFiles) noexcept;
 149    #endif
 150
 151 private:
 152     Process();
 153     JUCE_DECLARE_NON_COPYABLE (Process)
 154 };
 155
 156 } // namespace juce