### PyGuacamole Installation

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Instructions for installing the PyGuacamole library using pip or from source.

```APIDOC
## Installation

```bash
pip install pyguacamole
```

Or from source:

```bash
python setup.py install
```
```

--------------------------------

### GuacamoleBroker Server Example

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

A complete example demonstrating how to implement a Guacamole broker server using PyGuacamole, which mediates communication between a web browser and the guacd server.

```APIDOC
## Complete Broker Server Example

### Description
This example provides a full implementation of a `GuacamoleBroker` class. This class acts as a server that facilitates communication between a web client (e.g., a browser using Guacamole.js) and the `guacd` service. It handles establishing connections, reading instructions from `guacd`, and writing instructions received from the client to `guacd`.

### Method
```python
# Broker server logic
broker = GuacamoleBroker('127.0.0.1', 4822)
client_id = broker.connect(protocol='rdp', ...)
instruction = broker.read_from_guacd()
broker.write_to_guacd(browser_data)
broker.disconnect()
```

### Endpoint
N/A (This is a server implementation example, not a specific API endpoint)

### Parameters
N/A

### Request Body
N/A

### Request Example
```python
from guacamole.client import GuacamoleClient
from guacamole.instruction import GuacamoleInstruction
from guacamole.exceptions import GuacamoleError, InvalidInstruction
import threading

class GuacamoleBroker:
    """Broker server handling browser-guacd communication."""

    def __init__(self, guacd_host, guacd_port):
        self.guacd_host = guacd_host
        self.guacd_port = guacd_port
        self.client = None

    def connect(self, protocol, **connection_params):
        """Establish connection to guacd server."""
        self.client = GuacamoleClient(
            self.guacd_host,
            self.guacd_port,
            timeout=30,
            debug=False
        )

        try:
            self.client.handshake(protocol=protocol, **connection_params)
            return self.client.id
        except GuacamoleError as e:
            print(f"Connection failed: {e}")
            return None

    def read_from_guacd(self):
        """Read instruction from guacd (forward to browser)."""
        try:
            return self.client.receive()
        except Exception:
            return None

    def write_to_guacd(self, instruction):
        """Write instruction to guacd (from browser)."""
        try:
            self.client.send(instruction)
            return True
        except Exception:
            return False

    def disconnect(self):
        """Close connection."""
        if self.client:
            self.client.close()

# Usage example
broker = GuacamoleBroker('127.0.0.1', 4822)

# Connect to RDP server
client_id = broker.connect(
    protocol='rdp',
    hostname='windows-server.local',
    port=3389,
    username='admin',
    password='secret',
    width=1920,
    height=1080
)

if client_id:
    print(f"Connected with ID: {client_id}")

    # Read/write loop (simplified)
    instruction = broker.read_from_guacd()
    if instruction:
        # Forward to browser websocket
        print(f"To browser: {instruction}")

    # Receive from browser and forward to guacd
    browser_data = '5.mouse,3.100,3.200;'
    broker.write_to_guacd(browser_data)

    broker.disconnect()
```

### Response
#### Success Response (200)
N/A (This is a server implementation example)

#### Response Example
N/A
```

--------------------------------

### Install PyGuacamole

Source: https://github.com/mohabusama/pyguacamole/blob/master/README.rst

Methods for installing the PyGuacamole library via pip or from source code.

```bash
pip install pyguacamole
```

```bash
python setup.py install
```

--------------------------------

### Receive Instructions from Guacamole Server

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Shows how to use the `receive()` method to get raw instruction data from the guacd server. It returns a complete instruction string or None if the connection is lost, useful for forwarding to a browser.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Receive instruction from guacd server
instruction = client.receive()
print(instruction)
# Output: '4.size,1.0,4.1024,3.768;'

# Receive and forward to browser in a loop
while client.connected:
    instruction = client.receive()
    if instruction:
        # Forward to browser via WebSocket or other mechanism
        websocket.send(instruction)
    else:
        # Connection lost
        break
```

--------------------------------

### GuacamoleClient Initialization

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates how to create a GuacamoleClient instance and establish a connection to a guacd server with default or custom settings.

```APIDOC
## GuacamoleClient

The main client class for handling communication with the guacd server. It manages socket connections, handshakes, and bidirectional instruction flow.

### Creating a Client Connection

Creates a new GuacamoleClient instance and establishes a socket connection to the guacd server.

```python
from guacamole.client import GuacamoleClient

# Create client with default timeout (20 seconds)
client = GuacamoleClient('127.0.0.1', 4822)

# Create client with custom timeout and debug logging
client = GuacamoleClient(
    host='192.168.1.100',
    port=4822,
    timeout=30,
    debug=True
)

# Access the client ID after handshake
print(f"Client ID: {client.id}")

# Check connection status
print(f"Connected: {client.connected}")
```
```

--------------------------------

### Initialize and Handshake with Guacd

Source: https://github.com/mohabusama/pyguacamole/blob/master/README.rst

Demonstrates how to instantiate the GuacamoleClient and perform the initial handshake with a guacd server.

```python
from guacamole.client import GuacamoleClient
client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='localhost', port=3389)
```

--------------------------------

### Create GuacamoleClient Connection

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates how to instantiate the `GuacamoleClient` class to establish a connection with the guacd server. It shows creating a client with default settings and with custom timeouts and debug logging.

```python
from guacamole.client import GuacamoleClient

# Create client with default timeout (20 seconds)
client = GuacamoleClient('127.0.0.1', 4822)

# Create client with custom timeout and debug logging
client = GuacamoleClient(
    host='192.168.1.100',
    port=4822,
    timeout=30,
    debug=True
)

# Access the client ID after handshake
print(f"Client ID: {client.id}")

# Check connection status
print(f"Connected: {client.connected}")
```

--------------------------------

### Send Guacamole Protocol Instructions

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates how to send mouse and keyboard instructions to a connected Guacamole server using the GuacamoleClient. Requires an active handshake session.

```python
from guacamole.client import GuacamoleClient
from guacamole.instruction import GuacamoleInstruction

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Send a mouse instruction
mouse_instruction = GuacamoleInstruction('mouse', 400, 500, 0)
client.send_instruction(mouse_instruction)

# Send a key instruction
key_instruction = GuacamoleInstruction('key', 65, 1)  # Key 'A' pressed
client.send_instruction(key_instruction)
```

--------------------------------

### Sending and Receiving Instructions

Source: https://github.com/mohabusama/pyguacamole/blob/master/README.rst

Illustrates how to send instructions to the guacd server and receive instructions from it, which is crucial for broker server implementation.

```APIDOC
## Sending and Receiving Instructions

### Description
This section details the core communication methods of the `GuacamoleClient`: `receive()` to get instructions from `guacd` and `send()` to forward instructions to `guacd`. These methods are essential for a broker server that mediates between the `guacd` server and a browser-based Guacamole client.

### Method
N/A (This is a client-side library usage example)

### Endpoint
N/A (Client-side connection to a local or remote `guacd` service)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'client' is an initialized GuacamoleClient instance with an active handshake

# Receive an instruction from guacd
instruction_from_guacd = client.receive()
print(f"Received from guacd: {instruction_from_guacd}")
# Example output: '4.size,1.0,4.1024,3.768;'

# Send an instruction to guacd (e.g., mouse movement)
instruction_to_guacd = '5.mouse,3.400,3.500;'
client.send(instruction_to_guacd)
print(f"Sent to guacd: {instruction_to_guacd}")
```

### Response
#### Success Response (200)
N/A (These are client-side library usage examples. Success is indicated by the method returning data or executing without errors.)

#### Response Example
```
Received from guacd: 4.size,1.0,4.1024,3.768;
Sent to guacd: 5.mouse,3.400,3.500;
```
```

--------------------------------

### GuacamoleClient Initialization and Handshake

Source: https://github.com/mohabusama/pyguacamole/blob/master/README.rst

Demonstrates how to initialize the GuacamoleClient and establish a handshake with the guacd server for a specific protocol.

```APIDOC
## GuacamoleClient Initialization and Handshake

### Description
This section shows how to create an instance of the `GuacamoleClient` and initiate a handshake with the `guacd` server. The handshake involves specifying the connection protocol (e.g., 'rdp'), hostname, and port for the remote service.

### Method
N/A (This is a client-side library usage example)

### Endpoint
N/A (Client-side connection to a local or remote `guacd` service)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from guacamole.client import GuacamoleClient

# Initialize the client to connect to guacd on localhost:4822
client = GuacamoleClient('127.0.0.1', 4822)

# Establish a handshake for an RDP connection to localhost:3389
client.handshake(protocol='rdp', hostname='localhost', port=3389)
```

### Response
#### Success Response (200)
N/A (This is a client-side library usage example, success is indicated by the absence of exceptions during handshake)

#### Response Example
N/A
```

--------------------------------

### Send and Receive Instructions

Source: https://github.com/mohabusama/pyguacamole/blob/master/README.rst

Shows how to receive instructions from the guacd server and send instructions back to the server.

```python
instruction = client.receive()
print(instruction)

instruction_to_send = '5.mouse,3.400,3.500;'
client.send(instruction_to_send)
```

--------------------------------

### Manage GuacamoleClient Connection

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Shows how to initialize, use, and properly close a connection to a guacd server. Closing the connection resets the internal client state.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Perform operations...
instruction = client.receive()

# Close connection when done
client.close()
print(f"Connected: {client.connected")
```

--------------------------------

### Send Instructions to Guacamole Server

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates the `send()` method for transmitting raw encoded instruction strings to the guacd server. This is used for forwarding browser instructions, such as mouse movements or key presses.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Send mouse movement instruction
instruction = '5.mouse,3.400,3.500;'
client.send(instruction)

# Send key press instruction
key_instruction = '3.key,2.65,1.1;'  # Press 'A' key
client.send(key_instruction)

# Forward instruction from browser
browser_instruction = websocket.receive()
client.send(browser_instruction)
```

--------------------------------

### GuacamoleClient.receive()

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Receives raw instruction data from the guacd server. Returns a complete instruction string or None if the connection is lost.

```APIDOC
### GuacamoleClient.receive()

Receives raw instruction data from the guacd server. Returns a complete instruction string or None if the connection is lost.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Receive instruction from guacd server
instruction = client.receive()
print(instruction)
# Output: '4.size,1.0,4.1024,3.768;'

# Receive and forward to browser in a loop
while client.connected:
    instruction = client.receive()
    if instruction:
        # Forward to browser via WebSocket or other mechanism
        websocket.send(instruction)
    else:
        # Connection lost
        break
```
```

--------------------------------

### InvalidInstruction Handling

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Illustrates how to catch and manage InvalidInstruction exceptions, which are raised when Guacamole instruction strings are malformed, either during encoding or decoding.

```APIDOC
## InvalidInstruction Handling

### Description
This section demonstrates handling `InvalidInstruction` exceptions. These errors occur when the format of Guacamole instruction strings is incorrect, such as missing terminators, invalid argument lengths, or missing separators.

### Method
```python
# Example usage within a try-except block
try:
    GuacamoleInstruction.load('malformed_instruction')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")
```

### Endpoint
N/A (This is an exception handling example, not an API endpoint)

### Parameters
N/A

### Request Body
N/A

### Request Example
```python
from guacamole.instruction import GuacamoleInstruction
from guacamole.exceptions import InvalidInstruction

try:
    # Instruction missing terminator
    GuacamoleInstruction.load('4.args,8.hostname')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")
    # Expected Output: Invalid instruction: Invalid Guacamole Instruction! Instruction termination not found.

try:
    # Instruction with invalid argument length
    GuacamoleInstruction.load('5.args,8.hostname;')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")
    # Expected Output: Invalid instruction: Invalid Guacamole Instruction! Instruction arg (args) has invalid length.

try:
    # Instruction missing element separator
    GuacamoleInstruction.load('3args,8.hostname;')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")
    # Expected Output: Invalid instruction: Invalid Guacamole Instruction! Invalid arg length. Possibly due to missing element separator!
```

### Response
#### Success Response (200)
N/A (This is an exception handling example)

#### Response Example
N/A
```

--------------------------------

### Create and Encode Guacamole Instructions

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Illustrates how to instantiate a GuacamoleInstruction object and encode it into the wire-format required by the Guacamole protocol.

```python
from guacamole.instruction import GuacamoleInstruction

# Create instruction with opcode and args
instruction = GuacamoleInstruction('args', 'hostname', 'port', 1984)

# Encode instruction for transmission
encoded = instruction.encode()
print(encoded)

# Create mouse instruction
mouse = GuacamoleInstruction('mouse', 400, 500, 0)
print(mouse.encode())
```

--------------------------------

### Implement a Guacamole Broker Server

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Provides a complete class structure for a broker server that mediates communication between a browser and the guacd server. It includes methods for connecting, reading, writing, and disconnecting.

```python
from guacamole.client import GuacamoleClient
from guacamole.exceptions import GuacamoleError

class GuacamoleBroker:
    def __init__(self, guacd_host, guacd_port):
        self.guacd_host = guacd_host
        self.guacd_port = guacd_port
        self.client = None

    def connect(self, protocol, **connection_params):
        self.client = GuacamoleClient(self.guacd_host, self.guacd_port, timeout=30)
        try:
            self.client.handshake(protocol=protocol, **connection_params)
            return self.client.id
        except GuacamoleError as e:
            print(f"Connection failed: {e}")
            return None

    def read_from_guacd(self):
        return self.client.receive() if self.client else None

    def write_to_guacd(self, instruction):
        try:
            self.client.send(instruction)
            return True
        except Exception:
            return False

    def disconnect(self):
        if self.client: self.client.close()
```

--------------------------------

### Perform Guacamole Handshake

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Illustrates the `handshake()` method of `GuacamoleClient` for establishing a connection with guacd. It covers RDP, VNC, and SSH protocols, including options for display settings, credentials, and connecting to existing sessions.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)

# RDP connection handshake
client.handshake(
    protocol='rdp',
    hostname='windows-server.local',
    port=3389,
    username='admin',
    password='secret',
    width=1920,
    height=1080,
    dpi=96
)

# VNC connection handshake
client.handshake(
    protocol='vnc',
    hostname='linux-server.local',
    port=5900,
    password='vncpassword',
    width=1024,
    height=768
)

# SSH connection handshake
client.handshake(
    protocol='ssh',
    hostname='server.example.com',
    port=22,
    username='root',
    width=1024,
    height=768
)

# Connect to existing session using connection ID
client.handshake(
    connectionid='$260d01da-779b-4ee9-afc1-c16bae885cc7'
)

# Handshake with display overrides
client.handshake(
    protocol='rdp',
    hostname='server.local',
    port=3389,
    width=1024,
    height=768,
    width_override=1920,
    height_override=1080,
    dpi_override=120
)

# After successful handshake
print(f"Connection established with ID: {client.id}")
print(f"Connected: {client.connected}")
```

--------------------------------

### Handle Invalid Guacamole Instructions

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Shows how to catch InvalidInstruction exceptions when parsing malformed Guacamole protocol strings. This helps in validating data received from external sources.

```python
from guacamole.instruction import GuacamoleInstruction
from guacamole.exceptions import InvalidInstruction

try:
    GuacamoleInstruction.load('4.args,8.hostname')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")

try:
    GuacamoleInstruction.load('5.args,8.hostname;')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")

try:
    GuacamoleInstruction.load('3args,8.hostname;')
except InvalidInstruction as e:
    print(f"Invalid instruction: {e}")
```

--------------------------------

### GuacamoleError Handling

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates how to catch and handle GuacamoleError exceptions that occur during communication with the guacd server, such as protocol errors or connection failures.

```APIDOC
## GuacamoleError Handling

### Description
This section shows how to handle `GuacamoleError`, which is raised for protocol-level issues when communicating with the guacd server. This includes errors during the handshake process due to invalid protocols or connection disruptions.

### Method
```python
# Example usage within a try-except block
try:
    client.handshake(protocol='invalid_protocol')
except GuacamoleError as e:
    print(f"Protocol error: {e}")
```

### Endpoint
N/A (This is an exception handling example, not an API endpoint)

### Parameters
N/A

### Request Body
N/A

### Request Example
```python
from guacamole.client import GuacamoleClient
from guacamole.exceptions import GuacamoleError

client = GuacamoleClient('127.0.0.1', 4822)

try:
    # Attempting a handshake with an invalid protocol
    client.handshake(protocol='invalid_protocol')
except GuacamoleError as e:
    print(f"Protocol error: {e}")
    # Expected Output: Protocol error: Guacamole Protocol Error. Cannot start Handshake. Missing protocol or connectionid.

try:
    # Attempting a handshake that results in connection failure
    client.handshake(protocol='rdp')
except GuacamoleError as e:
    print(f"Connection error: {e}")
    # Expected Output: Protocol error: Guacamole Protocol Error. Cannot establish Handshake. Connection Lost!
```

### Response
#### Success Response (200)
N/A (This is an exception handling example)

#### Response Example
N/A
```

--------------------------------

### GuacamoleClient Methods

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Methods for managing the lifecycle of a Guacamole connection, including sending instructions and closing the connection.

```APIDOC
## POST /client/send_instruction

### Description
Sends a GuacamoleInstruction object after encoding it to the Guacamole protocol format.

### Method
POST

### Request Body
- **instruction** (GuacamoleInstruction) - Required - The instruction object to be sent.

### Request Example
{
  "opcode": "mouse",
  "args": [400, 500, 0]
}

## POST /client/close

### Description
Terminates the connection with the guacd server and resets the client state.

### Method
POST

### Response
#### Success Response (200)
- **connected** (boolean) - Returns false after successful closure.
```

--------------------------------

### Read and Decode Guacamole Instructions

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Explains how to use `read_instruction()` to receive and decode a single instruction from the guacd server into a `GuacamoleInstruction` object, providing access to its opcode and arguments.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Read and decode instruction
instruction = client.read_instruction()
print(f"Opcode: {instruction.opcode}")
print(f"Args: {instruction.args}")
# Output:
# Opcode: size
# Args: ('0', '1024', '768')
```

--------------------------------

### Parse and Load Guacamole Instructions

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Provides methods to load an instruction from a raw encoded string or decode it into a list of arguments for manual processing.

```python
from guacamole.instruction import GuacamoleInstruction

# Load instruction from encoded string
instruction_str = '4.args,8.hostname,4.port,4.1984;'
instruction = GuacamoleInstruction.load(instruction_str)

# Decode instruction to args list
args = GuacamoleInstruction.decode_instruction('4.size,4.1024,3.768;')
print(args)
```

--------------------------------

### Encode Individual Protocol Arguments

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates the static method to encode a single argument into the length-prefixed format required by the Guacamole protocol.

```python
from guacamole.instruction import GuacamoleInstruction

# Encode single argument
encoded = GuacamoleInstruction.encode_arg('size')
print(encoded)

encoded = GuacamoleInstruction.encode_arg(1024)
print(encoded)
```

--------------------------------

### GuacamoleClient.handshake()

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Establishes a connection with the guacd server using the Guacamole Protocol handshake. Supports various protocols (RDP, VNC, SSH) and connection parameters.

```APIDOC
### GuacamoleClient.handshake()

Establishes a connection with the guacd server using the Guacamole Protocol handshake sequence. Supports VNC, RDP, and SSH protocols with configurable display settings and connection parameters.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)

# RDP connection handshake
client.handshake(
    protocol='rdp',
    hostname='windows-server.local',
    port=3389,
    username='admin',
    password='secret',
    width=1920,
    height=1080,
    dpi=96
)

# VNC connection handshake
client.handshake(
    protocol='vnc',
    hostname='linux-server.local',
    port=5900,
    password='vncpassword',
    width=1024,
    height=768
)

# SSH connection handshake
client.handshake(
    protocol='ssh',
    hostname='server.example.com',
    port=22,
    username='root',
    width=1024,
    height=768
)

# Connect to existing session using connection ID
client.handshake(
    connectionid='$260d01da-779b-4ee9-afc1-c16bae885cc7'
)

# Handshake with display overrides
client.handshake(
    protocol='rdp',
    hostname='server.local',
    port=3389,
    width=1024,
    height=768,
    width_override=1920,
    height_override=1080,
    dpi_override=120
)

# After successful handshake
print(f"Connection established with ID: {client.id}")
print(f"Connected: {client.connected}")
```
```

--------------------------------

### GuacamoleClient.send()

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Sends raw encoded instruction strings to the guacd server. Used for forwarding instructions received from a client application.

```APIDOC
### GuacamoleClient.send()

Sends raw encoded instruction strings to the guacd server. Use this for forwarding instructions received from the browser.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Send mouse movement instruction
instruction = '5.mouse,3.400,3.500;'
client.send(instruction)

# Send key press instruction
key_instruction = '3.key,2.65,1.1;'  # Press 'A' key
client.send(key_instruction)

# Forward instruction from browser
browser_instruction = websocket.receive()
client.send(browser_instruction)
```
```

--------------------------------

### GuacamoleClient.read_instruction()

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Reads and decodes a single instruction from the guacd server, returning a structured GuacamoleInstruction object.

```APIDOC
### GuacamoleClient.read_instruction()

Reads and decodes an instruction from the guacd server, returning a GuacamoleInstruction object.

```python
from guacamole.client import GuacamoleClient

client = GuacamoleClient('127.0.0.1', 4822)
client.handshake(protocol='rdp', hostname='server.local', port=3389)

# Read and decode instruction
instruction = client.read_instruction()
print(f"Opcode: {instruction.opcode}")
print(f"Args: {instruction.args}")
# Output:
# Opcode: size
# Args: ('0', '1024', '768')
```
```

--------------------------------

### Handle Guacamole Protocol Errors

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Demonstrates how to catch GuacamoleError exceptions during the handshake process. This is essential for managing connection failures or invalid protocol configurations.

```python
from guacamole.client import GuacamoleClient
from guacamole.exceptions import GuacamoleError

client = GuacamoleClient('127.0.0.1', 4822)

try:
    client.handshake(protocol='invalid_protocol')
except GuacamoleError as e:
    print(f"Protocol error: {e}")

try:
    client.handshake(protocol='rdp')
except GuacamoleError as e:
    print(f"Connection error: {e}")
```

--------------------------------

### GuacamoleInstruction Class

Source: https://context7.com/mohabusama/pyguacamole/llms.txt

Utility methods for creating, encoding, and parsing Guacamole protocol instructions.

```APIDOC
## POST /instruction/encode

### Description
Creates a new instruction with an opcode and arguments, then encodes it for transmission.

### Request Body
- **opcode** (string) - Required - The instruction opcode.
- **args** (list) - Required - List of arguments.

## POST /instruction/load

### Description
Parses and loads a GuacamoleInstruction from an encoded instruction string received from the wire.

### Request Body
- **instruction_str** (string) - Required - The raw encoded string (e.g., '4.size,4.1024,3.768;').

## POST /instruction/decode

### Description
Static method that decodes an instruction string and returns a list of arguments (first element is the opcode).

### Request Body
- **instruction_str** (string) - Required - The raw encoded instruction string.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.