## Port Channel

Port Channel — private communication channel

## Stability Level

Stable, unless otherwise indicated

## Functions

void | spice_port_event ()
void | spice_port_write_async ()
gssize | spice_port_write_finish ()

## Properties

gchar * | port-name | Read
gboolean | port-opened | Read

## Signals

void | port-data | Run Last
void | port-event | Run Last

## Types and Values

struct | SpicePortChannel
struct | SpicePortChannelClass

## Object Hierarchy

        GObject
        ╰── SpiceChannel
            ╰── SpicePortChannel
                ╰── SpiceWebdavChannel

## Includes

    #include <channel-port.h>

## Description

A Spice port channel carry arbitrary data between the Spice client and the Spice server. It may be used to provide additional services on top of a Spice connection. For example, a channel can be associated with the qemu monitor for the client to interact with it, just like any qemu chardev. Or it may be used with various protocols, such as the Spice Controller.

A port kind is identified simply by a fqdn, such as org.qemu.monitor, org.spice.spicy.test or org.ovirt.controller...

Once connected and initialized, the client may read the name of the port via SpicePortChannel:port-name.

When the other end of the port is ready, SpicePortChannel:port-opened is set to `TRUE` and you can start receiving data via the signal SpicePortChannel::port-data, or sending data via `spice_port_write_async()`.

## Functions

### spice_port_event ()

    void
    spice_port_event (SpicePortChannel *port,
                      guint8 event);

Send an event to the port.

Note: The values SPICE_PORT_EVENT_CLOSED and SPICE_PORT_EVENT_OPENED are managed by the channel connection state.

#### Parameters

port | a SpicePortChannel |
event | a SPICE_PORT_EVENT value |

Since 0.15

### spice_port_write_async ()

    void
    spice_port_write_async (SpicePortChannel *port,
                            const void *buffer,
                            gsize count,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Request an asynchronous write of count bytes from `buffer` into the `port` . When the operation is finished `callback` will be called. You can then call `spice_port_write_finish()` to get the result of the operation.

#### Parameters

port | A SpicePortChannel |
buffer | the buffer containing the data to write. | [array length=count][element-type guint8]
count | the number of bytes to write |
cancellable | optional GCancellable object, NULL to ignore. | [allow-none]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since 0.15

### spice_port_write_finish ()

    gssize
    spice_port_write_finish (SpicePortChannel *port,
                             GAsyncResult *result,
                             GError **error);

Finishes a port write operation.

#### Parameters

port | a SpicePortChannel |
result | a GAsyncResult |
error | a GError location to store the error occurring, or `NULL` to ignore |

#### Returns

a gssize containing the number of bytes written to the stream.

Since 0.15

## Types and Values

### struct SpicePortChannel

    struct SpicePortChannel;

The SpicePortChannel struct is opaque and should not be accessed directly.

### struct SpicePortChannelClass

    struct SpicePortChannelClass {
        SpiceChannelClass parent_class;
    };

Class structure for SpicePortChannel.

#### Members

SpiceChannelClass `parent_class`; | Parent class. |

## Property Details

### The `“port-name”` property

      “port-name”                gchar *

Port name.

Flags: Read

Default value: NULL

### The `“port-opened”` property

      “port-opened”              gboolean

Port opened.

Flags: Read

Default value: FALSE

## Signal Details

### The `“port-data”` signal

    void
    user_function (SpicePortChannel *channel,
                   gpointer          data,
                   gint              size,
                   gpointer          user_data)

The “port-data” signal is emitted when new port data is received.

#### Parameters

channel | the channel that emitted the signal |
data | the data received |
size | number of bytes read |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 0.15

### The `“port-event”` signal

    void
    user_function (SpicePortChannel *channel,
                   gint              event,
                   gpointer          user_data)

The “port-event” signal is emitted when new port event is received.

#### Parameters

channel | the channel that emitted the signal |
event | the event received |
size | number of bytes read |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 0.15

## See Also

SpiceChannel