## Port Channel

Port Channel — private communication channel

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <channel-port.h>

    struct              SpicePortChannel;
    struct              SpicePortChannelClass;

    void                spice_port_event                    (SpicePortChannel *port,
                                                             guint8 event);
    void                spice_port_write_async              (SpicePortChannel *port,
                                                             const void *buffer,
                                                             gsize count,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gssize              spice_port_write_finish             (SpicePortChannel *port,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----SpiceChannel
             +----SpicePortChannel

## Properties

      "port-name"                gchar*                : Read
      "port-opened"              gboolean              : Read

## Signals

      "port-data"                                      : Run Last
      "port-event"                                     : Run Last

## 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()`.

## Details

### 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.

SpiceChannelClass `parent_class`; | Parent class.

### 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.

`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.

`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.

`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

## Property Details

### The `"port-name"` property

      "port-name"                gchar*                : Read

Port name.

Default value: NULL

### The `"port-opened"` property

      "port-opened"              gboolean              : Read

Port opened.

Default value: FALSE

## Signal Details

### The `"port-data"` signal

    void                user_function                      (SpicePortChannel *spiceportchannel,
                                                            gpointer          arg1,
                                                            gint              arg2,
                                                            gpointer          user_data)             : Run Last

### The `"port-event"` signal

    void                user_function                      (SpicePortChannel *spiceportchannel,
                                                            gint              arg1,
                                                            gpointer          user_data)             : Run Last

## See Also

SpiceChannel