wsutil/win32-utils.h

   1 /* win32-utils.h
   2  * Windows utility definitions
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 2006 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __WIN32UTIL_H__
  12 #define __WIN32UTIL_H__
  13
  14 #include <wireshark.h>
  15
  16 #include <windows.h>
  17
  18 /**
  19  * @file
  20  * Unicode convenience routines.
  21  */
  22
  23 #ifdef  __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /** Quote the argument element if necessary, so that it will get
  28  * reconstructed correctly in the C runtime startup code.  Note that
  29  * the unquoting algorithm in the C runtime is really weird, and
  30  * rather different than what Unix shells do. See stdargv.c in the C
  31  * runtime sources (in the Platform SDK, in src/crt).
  32  *
  33  * Stolen from GLib's protect_argv(), an internal routine that quotes
  34  * string in an argument list so that they arguments will be handled
  35  * correctly in the command-line string passed to CreateProcess()
  36  * if that string is constructed by gluing those strings together.
  37  *
  38  * @param argv The string to be quoted.  May be NULL.
  39  * @return The string quoted to be used by CreateProcess
  40  */
  41 WS_DLL_PUBLIC
  42 char * protect_arg (const char *argv);
  43
  44 /** Tests a UTF-8 string to see if it is a Windows pipe name.
  45  * Under Windows, named pipes _must_ have the form "\\<server>\pipe\<pipename>".
  46  * <server> may be "." for localhost. This does not check that a pipe server
  47  * has actually created the pipe, only that the name is the proper form.
  48  *
  49  * @param pipename The UTF-8 string to be checked
  50  * @return TRUE if the string is a valid Windows pipe name.
  51  */
  52 WS_DLL_PUBLIC
  53 bool win32_is_pipe_name(const char* pipe_name);
  54
  55 /** Generate a string for a Windows error.
  56  *
  57  * @param error The Windows error code
  58  * @return a localized UTF-8 string containing the corresponding error message
  59  */
  60 WS_DLL_PUBLIC
  61 const char * win32strerror(DWORD error);
  62
  63 /** Generate a string for a Win32 exception code.
  64  *
  65  * @param exception The exception code
  66  * @return a non-localized string containing the error message
  67  */
  68 WS_DLL_PUBLIC
  69 const char * win32strexception(DWORD exception);
  70
  71 /**
  72  * @brief ws_pipe_create_process Create a process and assign it to the main application
  73  *        job object so that it will be killed when the main application exits.
  74  *
  75  * In order to limit unwanted handle duplicates in subprocesses all handles should be
  76  * created as not inheritable and passed in the inherit_handles array. This function
  77  * marks the handles as inheritable for as short time as possible. Note that handles
  78  * passed to this function will have the inheritable flag cleared on exit. Processes
  79  * created with this function inherit only the provided handles.
  80  *
  81  * @param application_name Application name. Will be converted to its UTF-16 equivalent or NULL.
  82  * @param command_line Command line. Will be converted to its UTF-16 equivalent.
  83  * @param process_attributes Same as CreateProcess.
  84  * @param thread_attributes Same as CreateProcess.
  85  * @param n_inherit_handles Number of handles the child process will inherit.
  86  * @param inherit_handles Handles the child process will inherit.
  87  * @param creation_flags Will be ORed with CREATE_SUSPENDED|CREATE_BREAKAWAY_FROM_JOB.
  88  * @param environment Same as CreateProcess.
  89  * @param current_directory Current directory. Will be converted to its UTF-16 equivalent or NULL.
  90  * @param startup_info Same as CreateProcess.
  91  * @param process_information Same as CreateProcess.
  92  * @return
  93  */
  94 WS_DLL_PUBLIC
  95 BOOL win32_create_process(const char *application_name, const char *command_line,
  96     LPSECURITY_ATTRIBUTES process_attributes, LPSECURITY_ATTRIBUTES thread_attributes,
  97     size_t n_inherit_handles, HANDLE *inherit_handles,
  98     DWORD creation_flags, LPVOID environment,
  99     const char *current_directory, LPSTARTUPINFO startup_info, LPPROCESS_INFORMATION process_information
 100 );
 101
 102 #ifdef  __cplusplus
 103 }
 104 #endif
 105
 106 #endif /* __WIN32UTIL_H__ */