GNetworkConnection

GNetworkConnection — The interface for connection-based protocol objects.

Synopsis




            GNetworkConnection;
enum        GNetworkConnectionStatus;
enum        GNetworkConnectionType;
void        gnetwork_connection_open        (GNetworkConnection *connection);
void        gnetwork_connection_close       (GNetworkConnection *connection);
void        gnetwork_connection_send        (GNetworkConnection *connection,
                                             gconstpointer data,
                                             glong length);
            GNetworkConnectionIface;
void        gnetwork_connection_received    (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gulong length);
void        gnetwork_connection_sent        (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gulong length);
void        gnetwork_connection_error       (GNetworkConnection *connection,
                                             const GError *error);
void        (*GNetworkConnectionFunc)       (GNetworkConnection *connection);
void        (*GNetworkConnectionSendFunc)   (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gsize length);
#define     GNETWORK_CONNECTION_CALL_PARENT (obj,method,args)

Object Hierarchy


  GInterface
   +----GNetworkConnection

Prerequisites

GNetworkConnection requires GObject.

Known Implementations

GNetworkConnection is implemented by GNetworkTcpConnection and GNetworkUnixConnection.

Properties


  "buffer-size"          guint                 : Read / Write / Construct
  "bytes-received"       gulong                : Read
  "bytes-sent"           gulong                : Read
  "connection-type"      GNetworkConnectionType  : Read / Write / Construct
  "status"               GNetworkConnectionStatus  : Read

Signals


"error"     void        user_function      (GNetworkConnection *gnetworkconnection,
                                            GError             *arg1,
                                            gpointer            user_data)               : Run first / Has details
"received"  void        user_function      (GNetworkConnection *gnetworkconnection,
                                            gpointer            arg1,
                                            gulong              arg2,
                                            gpointer            user_data)               : Run first
"sent"      void        user_function      (GNetworkConnection *gnetworkconnection,
                                            gpointer            arg1,
                                            gulong              arg2,
                                            gpointer            user_data)               : Run first

Description

The GNetworkConnectionIface interface provides a standard set of methods and signals for connection-based socket objects. Examples of connection-based socket objects are TCP/IP and the Unix stream IPC protocol.

A connection is a particular type of socket,

Details

GNetworkConnection

typedef struct _GNetworkConnection GNetworkConnection;

An empty typedef for objects which implement the GNetworkConnectionIface interface.

enum GNetworkConnectionStatus

typedef enum /* <prefix=GNETWORK_CONNECTION> */
{
  GNETWORK_CONNECTION_CLOSING,
  GNETWORK_CONNECTION_CLOSED,
  GNETWORK_CONNECTION_OPENING,
  GNETWORK_CONNECTION_OPEN
}
GNetworkConnectionStatus;

An enumeration of the possible connection states a GNetworkConnectionIface implementation may be in.

GNETWORK_CONNECTION_CLOSING the connection is in the process of closing.
GNETWORK_CONNECTION_CLOSED the connection is closed.
GNETWORK_CONNECTION_OPENING the connection is in the process of opening.
GNETWORK_CONNECTION_OPEN the connection is open.

enum GNetworkConnectionType

typedef enum /* <prefix=GNETWORK_CONNECTION> */
{
  GNETWORK_CONNECTION_INVALID,

  GNETWORK_CONNECTION_CLIENT,
  GNETWORK_CONNECTION_SERVER
}
GNetworkConnectionType;

An enumeration of the types of connections that can exist.

GNETWORK_CONNECTION_INVALID an invalid connection.
GNETWORK_CONNECTION_CLIENT a client connection.
GNETWORK_CONNECTION_SERVER a server connection.

gnetwork_connection_open ()

void        gnetwork_connection_open        (GNetworkConnection *connection);

Starts the connection process for connection.

connection : the connection to open.

Since 1.0

gnetwork_connection_close ()

void        gnetwork_connection_close       (GNetworkConnection *connection);

Closes the connection in question.

connection : the connection to close.

Since 1.0

gnetwork_connection_send ()

void        gnetwork_connection_send        (GNetworkConnection *connection,
                                             gconstpointer data,
                                             glong length);

Sends the data in data through connection. If length is less than one, data is assumed to be terminated by 0. This function will perform the necessary calculations for length. After calling the implementation's send function, the "send" signal will be emitted.

connection : the connection to send through.
data : the data to send.
length : the length in bytes of data.

Since 1.0

GNetworkConnectionIface

typedef struct {
  /* Signals */
  void (*received)           (GNetworkConnection * connection,
			      gconstpointer data,
			      gulong length);
  void (*sent)		     (GNetworkConnection * connection,
			      gconstpointer data,
			      gulong length);
  void (*error)		     (GNetworkConnection * connection,
			      GError * error);

  /* Methods */
  GNetworkConnectionFunc      open;
  GNetworkConnectionFunc      close;
  GNetworkConnectionSendFunc  send;
} GNetworkConnectionIface;

The interface structure for implementers.

received () the slot for the "received" signal.
sent () the slot for the "sent" signal.
error () the slot for the "error" signal.
GNetworkConnectionFunc open; the open method.
GNetworkConnectionFunc close; the close method.
GNetworkConnectionSendFunc send; the send method.

gnetwork_connection_received ()

void        gnetwork_connection_received    (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gulong length);

Emits the "received" signal for connection, using the values in data and length. Implementations of the GNetworkConnectionIface interface should use this function when data has been received.

connection : the connection to use.
data : the data being recieved.
length : the length of data in bytes.

Since 1.0

gnetwork_connection_sent ()

void        gnetwork_connection_sent        (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gulong length);

Emits the "sent" signal for connection, using the values in data and length. Implementations of the GNetworkConnectionIface interface should call this function when data has been sent.

connection : the connection to use.
data : the data which was sent.
length : the length of data in bytes.

Since 1.0

gnetwork_connection_error ()

void        gnetwork_connection_error       (GNetworkConnection *connection,
                                             const GError *error);

Emits the "error" signal for connection, using error. Callers to this function should use their own error domains.

connection : the connection to use.
error : the error structure.

Since 1.0

GNetworkConnectionFunc ()

void        (*GNetworkConnectionFunc)       (GNetworkConnection *connection);

A basic implementation function type.

connection : the connection object.

GNetworkConnectionSendFunc ()

void        (*GNetworkConnectionSendFunc)   (GNetworkConnection *connection,
                                             gconstpointer data,
                                             gsize length);

An implementation function type used to send data.

connection : the connection object.
data : the data to be sent.
length : the length of data in bytes.

GNETWORK_CONNECTION_CALL_PARENT()

#define     GNETWORK_CONNECTION_CALL_PARENT(obj,method,args)

A macro to call a parent class' GNetworkConnectionIface implementation of method. Typically, this would be used to "chain up" after overriding a method or signal callback.

obj : the object in question.
method : the method to call.
args : the arguments to pass method.

Property Details

The "buffer-size" property

  "buffer-size"          guint                 : Read / Write / Construct

The maximum size in bytes of outgoing and incoming data packets.

Default value: 2048

The "bytes-received" property

  "bytes-received"       gulong                : Read

The number of bytes received through this connection.

The "bytes-sent" property

  "bytes-sent"           gulong                : Read

The number of bytes sent through this connection.

The "connection-type" property

  "connection-type"      GNetworkConnectionType  : Read / Write / Construct

The type of connection represented by the implementing object.

Default value: GNETWORK_CONNECTION_CLIENT

The "status" property

  "status"               GNetworkConnectionStatus  : Read

The status of this connection.

Default value: GNETWORK_CONNECTION_CLOSED

Signal Details

The "error" signal

void        user_function                  (GNetworkConnection *gnetworkconnection,
                                            GError             *arg1,
                                            gpointer            user_data)               : Run first / Has details

This signal is emitted when an error occurs in the connection.

gnetworkconnection : the object which received the signal.
arg1 : the error structure.
user_data : user data set when the signal handler was connected.

The "received" signal

void        user_function                  (GNetworkConnection *gnetworkconnection,
                                            gpointer            arg1,
                                            gulong              arg2,
                                            gpointer            user_data)               : Run first

This signal is emitted when data has been received.

gnetworkconnection : the object which received the signal.
arg1 : the data which was received.
arg2 : the size of data, in bytes.
user_data : user data set when the signal handler was connected.

The "sent" signal

void        user_function                  (GNetworkConnection *gnetworkconnection,
                                            gpointer            arg1,
                                            gulong              arg2,
                                            gpointer            user_data)               : Run first

This signal is emitted when data has been sent.

gnetworkconnection : the object which received the signal.
arg1 : the data which was sent.
arg2 : the size of data, in bytes.
user_data : user data set when the signal handler was connected.