# salt.modules.win_shortcut

Execution module for creating shortcuts on Windows. Handles file shortcuts (.lnk) and url shortcuts (.url). Allows for the configuration of icons and hot keys on file shortcuts. Changing the icon and hot keys are unsupported for url shortcuts.

Added in version 3005.

salt.modules.win_shortcut.create(path, target, arguments='', description='', hot_key='', icon_index=0, icon_location='', window_style='Normal', working_dir='', backup=False, force=False, make_dirs=False, user=None)

  Create a new shortcut. This can be a file shortcut (`.lnk`) or a url shortcut (`.url`).

  Parameters:

    - path (str) -- The full path to the shortcut. Must have a .lnk or .url file extension.

    - target (str) -- The full path to the target

    - arguments (str, optional) -- Any arguments to be passed to the target

    - description (str, optional) -- The description for the shortcut. This is shown in the `Comment` field of the dialog box. Default is an empty string

    - hot_key (str, optional) --

      A combination of hot Keys to trigger this shortcut. This is something like `Ctrl+Alt+D`. This is shown in the `Shortcut key` field in the dialog box. Default is an empty string. Available options are:

      - Ctrl

      - Alt

      - Shift

      - Ext

    - icon_index (int, optional) -- The index for the icon to use in files that contain multiple icons. Default is 0

    - icon_location (str, optional) -- The full path to a file containing icons. This is shown in the `Change Icon` dialog box by clicking the `Change Icon` button. If no file is specified and a binary is passed as the target, Windows will attempt to get the icon from the binary file. Default is an empty string

    - window_style (str, optional) --

      The window style the program should start in. This is shown in the `Run` field of the dialog box. Default is `Normal`. Valid options are:

      - Normal

      - Minimized

      - Maximized

    - working_dir (str, optional) -- The full path to the working directory for the program to run in. This is shown in the `Start in` field of the dialog box.

    - backup (bool, optional) -- If there is already a shortcut with the same name, set this value to `True` to backup the existing shortcut and continue creating the new shortcut. Default is `False`

    - force (bool, optional) -- If there is already a shortcut with the same name and you aren't backing up the shortcut, set this value to `True` to remove the existing shortcut and create a new with these settings. Default is `False`

    - make_dirs (bool, optional) -- If the parent directory structure does not exist for the new shortcut, create it. Default is `False`

    - user (str, optional) -- The user to be the owner of any directories created by setting `make_dirs` to `True`. If no value is passed Salt will use the user account that it is running under. Default is an empty string.

  Returns:

    True if successful

  Return type:

    bool

  Raises:

    - CommandExecutionError -- If the path is not a `.lnk` or `.url` file extension.

    - CommandExecutionError -- If there is an existing shortcut with the same name and `backup` and `force` are both `False`

    - CommandExecutionError -- If the parent directory is not created and `make_dirs` is `False`

    - CommandExecutionError -- If there was an error creating the parent directories

  CLI Example:

      # Create a shortcut and set the ``Shortcut key`` (``hot_key``)
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" hot_key="Ctrl+Alt+N"

      # Create a shortcut and change the icon to the 3rd one in the icon file
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" icon_location="C:\path\to\icon.ico" icon_index=2

      # Create a shortcut and change the startup mode to full screen
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" window_style="Maximized"

      # Create a shortcut and change the icon
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" icon_location="C:\path\to\icon.ico"

      # Create a shortcut and force it to overwrite an existing shortcut
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" force=True

      # Create a shortcut and create any parent directories if they are missing
      salt * shortcut.create "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe" make_dirs=True

salt.modules.win_shortcut.get(path)

  Gets the properties for a shortcut

  Parameters:

    path (str) -- The path to the shortcut. Must have a .lnk or .url file extension.

  Returns:

    A dictionary containing all available properties for the specified

      shortcut

  Return type:

    dict

  CLI Example:

      salt * shortcut.get path="C:\path\to\shortcut.lnk"

salt.modules.win_shortcut.modify(path, target='', arguments='', description='', hot_key='', icon_index=0, icon_location='', window_style='Normal', working_dir='')

  Modify an existing shortcut. This can be a file shortcut (`.lnk`) or a url shortcut (`.url`).

  Parameters:

    - path (str) -- The full path to the shortcut. Must have a .lnk or .url file extension.

    - target (str, optional) -- The full path to the target

    - arguments (str, optional) -- Any arguments to be passed to the target

    - description (str, optional) -- The description for the shortcut. This is shown in the `Comment` field of the dialog box. Default is an empty string

    - hot_key (str, optional) --

      A combination of hot Keys to trigger this shortcut. This is something like `Ctrl+Alt+D`. This is shown in the `Shortcut key` field in the dialog box. Default is an empty string. Available options are:

      - Ctrl

      - Alt

      - Shift

      - Ext

    - icon_index (int, optional) -- The index for the icon to use in files that contain multiple icons. Default is 0

    - icon_location (str, optional) -- The full path to a file containing icons. This is shown in the `Change Icon` dialog box by clicking the `Change Icon` button. If no file is specified and a binary is passed as the target, Windows will attempt to get the icon from the binary file. Default is an empty string

    - window_style (str, optional) --

      The window style the program should start in. This is shown in the `Run` field of the dialog box. Default is `Normal`. Valid options are:

      - Normal

      - Minimized

      - Maximized

    - working_dir (str, optional) -- The full path to the working directory for the program to run in. This is shown in the `Start in` field of the dialog box.

  Returns:

    True if successful

  Return type:

    bool

  CLI Example:

      # Modify an existing shortcut. Set it to target notepad.exe
      salt * shortcut.modify "C:\path\to\shortcut.lnk" "C:\Windows\notepad.exe"