/* NetworkVolumeManager.h
 *  
 * Author: Simon Peter
 * Date: January 2026
 *
 * Manages mounting and unmounting of network volumes (SFTP, WebDAV, AFP, etc.)
 */

#import <Foundation/Foundation.h>

@class NetworkServiceItem;

/**
 * NetworkVolumeManager handles the mounting and unmounting of network
 * volumes using platform-specific tools like FUSE sshfs on Linux/BSD,
 * and AVFS for WebDAV, FTP, HTTP access.
 *
 * This class provides an abstraction layer over different mounting mechanisms
 * and handles error conditions gracefully.
 */
@interface NetworkVolumeManager : NSObject
{
  NSMutableDictionary *mountedVolumes;  /* Maps service identifier to mount point */
  NSMutableDictionary *mountedVolumesPIDs;  /* Maps service identifier to NSNumber(pid) */
  NSMutableDictionary *webdavMounts;    /* Maps service identifier to AVFS virtual path */
  NSFileManager *fm;
  NSString *lastErrorMessage;  /* Last mount error for callers to retrieve */
  NSMutableSet *recentlyUnmountedPaths;  /* Paths recently unmounted, for dialog suppression */
}

/**
 * Returns the last error message from a failed mount operation.
 * Callers on the main thread can use this to show a proper error dialog.
 */
- (NSString *)lastErrorMessage;

/**
 * Returns the shared singleton instance.
 */
+ (NetworkVolumeManager *)sharedManager;

/**
 * Attempts to mount an SFTP service at a standard mount point.
 * Returns the mount point path on success, nil on failure.
 *
 * This method checks if sshfs is available and prompts the user if it's not.
 *
 * @param serviceItem The SFTP service to mount
 * @return The path where the service was mounted, or nil on failure
 */
- (NSString *)mountSFTPService:(NetworkServiceItem *)serviceItem;

/**
 * Attempts to mount an SFTP service with provided credentials.
 * Returns the mount point path on success, nil on failure.
 * This version does not prompt the user for credentials.
 *
 * @param serviceItem The SFTP service to mount
 * @param user The username to use (required)
 * @param pass The password to use (optional, uses SSH keys if nil)
 * @return The path where the service was mounted, or nil on failure
 */
- (NSString *)mountSFTPService:(NetworkServiceItem *)serviceItem
                      username:(NSString *)user
                      password:(NSString *)pass;

/**
 * Unmounts a previously mounted network service.
 *
 * @param serviceItem The service to unmount
 * @return YES if unmounted successfully, NO otherwise
 */
- (BOOL)unmountService:(NetworkServiceItem *)serviceItem;

/**
 * Unmounts a mount by its mount point path. Returns YES if successful.
 */
- (BOOL)unmountPath:(NSString *)path;

/**
 * Returns the mount point for a given service, if currently mounted.
 *
 * @param serviceItem The service to check
 * @return The mount point path, or nil if not mounted
 */
- (NSString *)mountPointForService:(NetworkServiceItem *)serviceItem;

/**
 * Returns YES if the given service is currently mounted.
 */
- (BOOL)isServiceMounted:(NetworkServiceItem *)serviceItem;

/**
 * Checks if sshfs (FUSE) is available on the system.
 *
 * @return YES if sshfs is available, NO otherwise
 */
- (BOOL)isSshfsAvailable;

/**
 * Attempts to mount a WebDAV service using AVFS.
 * Returns the virtual path on success, nil on failure.
 *
 * This method checks if AVFS is available and prompts the user if it's not.
 * Will prompt for credentials if needed.
 *
 * @param serviceItem The WebDAV service to mount
 * @return The AVFS virtual path, or nil on failure
 */
- (NSString *)mountWebDAVService:(NetworkServiceItem *)serviceItem;

/**
 * Attempts to mount a WebDAV service with provided credentials.
 * Returns the virtual path on success, nil on failure.
 *
 * @param serviceItem The WebDAV service to mount
 * @param user The username to use (optional)
 * @param pass The password to use (optional)
 * @return The AVFS virtual path, or nil on failure
 */
- (NSString *)mountWebDAVService:(NetworkServiceItem *)serviceItem
                        username:(NSString *)user
                        password:(NSString *)pass;

/**
 * Unmounts all currently mounted network volumes.
 * Typically called during application shutdown.
 */
- (void)unmountAll;

/**
 * Returns a set of all currently mounted network volume paths.
 * Used by the sidebar to exclude network mounts from the Volumes section.
 *
 * @return NSSet of NSString mount point paths
 */
- (NSSet *)allMountedPaths;

/**
 * Returns a set of paths that were recently unmounted network volumes.
 * Used by GWDesktopView to suppress "Volume Removed Unexpectedly" dialogs.
 *
 * @return NSSet of NSString paths unmounted within the last few seconds
 */
- (NSSet *)recentlyUnmountedPaths;

/**
 * Runs a modal credentials panel (username/password) for a network service.
 * Returns a dictionary with keys @"username" and @"password" on success,
 * or nil if the user cancelled.
 *
 * @param title The window title (e.g. "Connect to SFTP Server")
 * @param hostname The hostname to display in the prompt
 * @return NSDictionary with @"username" and @"password", or nil on cancel
 */
+ (NSDictionary *)runCredentialsPanelWithTitle:(NSString *)title
                                      hostname:(NSString *)hostname;

@end
