In previous blogs, we have implemented custom protocols on both Win32 and MacOS. This time, we are going to implement it on Linux with GDBus and GTK3+. I am using Almalinux 8.7. There could be some differences between it and other distros, please check the manual of your targeting distro and make changes accordingly.
To register a protocol for application on Linux, you will need to create a .desktop for your application in /usr/share/applications
[Desktop Entry]
Name=APSShellDemo
Comment=Demo for shell launching with Linux
GenericName=APSShelldemo
Exec=YourPathToExec %U
Type=Application
StartupNotify=true
Categories=Development
MimeType=x-scheme-handler/apsshelldemoWe need to add a %U parameter for our application in Exec option.
The MimeType option will register a protocol for our application. Our protocol is apsshelldemo, so it is x-scheme-handler/apsshelldemo.
After creating it, you may need to update the cache of your desktop system to make it work. Run the following command in the terminal.
sudo update-desktop-databaseWe'll use GTK+, DBUS, GLIB, GIO, GObject libraries in our sample. Please make sure they are installed on your system.
Let's begin with a simple ui. For AlmaLinux 8, it provides GTK3+. There are some changes in GTK4+, if you are using a newer version of GTK+, please update the code according to the manual.
The sample provided by GTK3+ tutorial is a good start. We'll add a label for displaying the APS client id and update it with 3-legged code after receving it from browser. We'll also create a button that could open a browser for authentication. The client id will be retrieved from APS_CLIENT_ID environment variable, please add it before you are running the application. I usually put them inside etc/profile.d, so I could have environment set after booting up my system.
#include <gtk/gtk.h>
#include <cstdlib>
#include <cstdio>
const char *authAddressFMT = "https://developer.api.autodesk.com/authentication/v2/authorize?response_type=code"
"&client_id=%s"
"&redirect_uri=apsshelldemo://oauth"
"&scope=data:read%%20data:create%%20data:write";
// callback function which is called when button is clicked
static void on_button_clicked(GtkButton *btn, gpointer data) {
// Let's generate the uri.
char buffer[1024];
auto env = std::getenv("APS_CLIENT_ID");
if (NULL == env) {
env = "";
}
std::snprintf(buffer, 1024, authAddressFMT, env);
// Launch our uri in a window.
gtk_show_uri_on_window(NULL, buffer, GDK_CURRENT_TIME, NULL);
}
// callback function which is called when application is first started
static void on_app_activate(GApplication *app, gpointer data) {
// create a new application window for the application
// GtkApplication is sub-class of GApplication
// downcast GApplication* to GtkApplication* with GTK_APPLICATION() macro
GtkWidget *window = gtk_application_window_new(GTK_APPLICATION(app));
GtkWidget *vbox = gtk_box_new(GtkOrientation::GTK_ORIENTATION_VERTICAL, 5);
gtk_widget_set_margin_start(vbox,5);
gtk_widget_set_margin_end(vbox,5);
gtk_widget_set_margin_top(vbox,5);
gtk_widget_set_margin_bottom(vbox,5);
// Check if APS_CLIENT_ID exists
// We can add it through user profile or ide environment.
// If we want to add it system-wide, we can add it to /etc/environment
char buffer[256];
auto env = getenv("APS_CLIENT_ID");
if (NULL == env){
std::sprintf(buffer,"You need to set APS_CLIENT_ID in your environment variables.");
}
else{
std::sprintf(buffer,"CLIENT ID:%s", env);
}
// Create UI
GtkWidget *label = gtk_label_new(buffer);
GtkWidget *btn = gtk_button_new_with_label("Do Auth!");
// connect the event-handler for "clicked" signal of button
g_signal_connect(btn, "clicked", G_CALLBACK(on_button_clicked), NULL);
// add the button to the window
gtk_container_add(GTK_CONTAINER(vbox), btn);
gtk_container_add(GTK_CONTAINER(vbox), label);
gtk_container_add(GTK_CONTAINER(window), vbox);
// display the window
gtk_widget_show_all(GTK_WIDGET(window));
}
int main(int argc, char *argv[]) {
// create new GtkApplication with an unique application ID
GtkApplication *app = gtk_application_new(
"DAS.APSShellDemo",
G_APPLICATION_FLAGS_NONE
);
// connect the event-handler for "activate" signal of GApplication
// G_CALLBACK() macro is used to cast the callback function pointer
// to generic void pointer
g_signal_connect(app, "activate", G_CALLBACK(on_app_activate), NULL);
// start the application, terminate by closing the window
// GtkApplication* is upcast to GApplication* with G_APPLICATION() macro
int status = g_application_run(G_APPLICATION(app), 0, 0);
// deallocate the application object
g_object_unref(app);
return status;
}The result:
Now we have a basic window. Let's figure out how to make it a single instance app.
On linux, the easiest way to make your program single instance is to use file lock. We'll try to acquire a file lock when the program is started. If we failto acquire the lock, we'll send the url through D-Bus and exit.
#include <fcntl.h>
#include <unistd.h>
...
int main(int argc, char *argv[]) {
// We are using file lock here, alternatives could be socket or a semaphore
int fd = open ("/tmp/apsshelldemo.pid", O_CREAT | O_RDWR, 0666);
if(lockf(fd, F_TLOCK, 0) == 0) {
// create new GtkApplication with an unique application ID
GtkApplication *app = gtk_application_new(
"DAS.APSShellDemo",
G_APPLICATION_FLAGS_NONE
);
...
lockf(fd, F_ULOCK, 0);
close(fd);
return status;
}
else
{
//TODO: Implement D-Bus client.
return 0;
}
}Next is the IPC part. Like other operating systems, there are several ways to send messages between processes. We'll use D-Bus here. It is widely used and easily to implement (sort of). The naive D-Bus library isn't recommended to use directly as the document suggested
If you use this low-level API directly, you're signing up for some pain.
As an alternative, There are several libraries for using D-Bus(e.g., QDBus, GDBus…). We are going to use GDBus provided by GIO here to make things simpler.
Let's begin with some consts and structs.
#include <gio/gio.h>
...
// Some consts for our well-known D-Bus service
const char *dbus_object_path = "/das/apsshelldemo/object";
const char *dbus_interface_name = "das.apsshelldemo";
const char *dbus_method_name = "doOAuth";
const char *dbus_well_known_name = "das.apshelldemo.dbusserver";
// D-Bus ids.
static guint registration_id;
static guint owner_id;
// Accessing GTK items in the dbus callback
typedef struct {
GApplication *app;
GtkLabel *label;
}UserData;
...To publish and call a service, you'll need to provide introspection data in XML format for D-Bus. Let's add it after the struct we've defined above.
...
// We'll generate GDBusNodeInfo from XML and store it.
static GDBusNodeInfo *introspection_data = NULL;
// This XML defines our method interface for clients calling
static const gchar introspection_xml[] =
"<node>"
"<interface name='das.apsshelldemo'>"
"<method name='doOAuth'>"
"<arg name='message' type='s' direction='in'/>"
"</method>"
"</interface>"
"</node>";
...Next, we'll create our function for processing a remote call and add it to a GDBusInterfaceVTable struct. This struct will be used for registering D-Bus service later on. Let's continue with the end of previous XML const.
...
// This is the method for handling dbus method call.
static void handle_method_call (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
GDBusMethodInvocation *invocation,
gpointer user_data) {
// Check which method is calling. We only have one method here.
if (g_strcmp0(method_name, dbus_method_name) == 0)
{
const gchar *message;
g_variant_get (parameters, "(&s)", &message);
if (g_strcmp0 (message, "Return Unregistered") == 0 || g_strcmp0(message, "Return Registered") == 0 ||
g_strcmp0(message, "Return Raw") ==0)
{
// Error, do nothing
}else{
// Unwrap our user data and set the label.
GtkLabel *label = ((UserData *)user_data)->label;
gtk_label_set_text(label, message);
}
}
// Return NULL to allow client continue.
g_dbus_method_invocation_return_value(invocation, NULL);
}
// We only want to handle method calling here
static const GDBusInterfaceVTable interface_vtable =
{
handle_method_call,
NULL,
NULL,
{ 0 }
};
...Now we have set up the remote interface we are going to create. We'll add some callbacks for setup and cleanup the D-Bus. Let's continue.
...
// Free user data
static void user_data_free(gpointer data){
delete data;
}
// Register D-Bus object after acquring the bus.
static void on_bus_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
registration_id = g_dbus_connection_register_object (connection,
dbus_object_path,
introspection_data->interfaces[0],
&interface_vtable,
user_data, /* user_data */
user_data_free, /* user_data_free_func /
NULL); /* GError** */
}
static void on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
}
// We would like to close our application when name is lost.
static void on_name_lost (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
UserData *data = (UserData*)user_data;
// exit
g_application_quit(data->app);
}
...Let's initialize our D-Bus in the activation of our main window.
...
static void on_app_activate(GApplication *app, gpointer data) {
...
gtk_container_add(GTK_CONTAINER(window), vbox);
// Let's setup our D-Bus through GDBus
// Using XML to create our introspection is easier.
introspection_data = g_dbus_node_info_new_for_xml (introspection_xml, NULL);
// We'll wrap our GTK widgets in user data and use them in the D-Bus callback.
UserData *user_data = new UserData();
user_data->app = app;
user_data->label = (GtkLabel*)label;
// Let's connect to D-Bus!
// We are using the bus of login session.
owner_id = g_bus_own_name(G_BUS_TYPE_SESSION,
dbus_well_known_name,
G_BUS_NAME_OWNER_FLAGS_NONE,
on_bus_acquired,
on_name_acquired,
on_name_lost,
user_data,
user_data_free);
// display the window
gtk_widget_show_all(GTK_WIDGET(window));
}Finally, let's update our program entry. Because D-Bus is initialized after the UI is activated. We only need to cleanup in the main process.
...
// Deallocate the application object
g_object_unref(app);
g_dbus_connection_unregister_object(g_bus_get_sync(G_BUS_TYPE_SESSION,NULL,NULL), registration_id);
g_bus_unown_name(owner_id);
// Unlock our pid file.
lockf(fd, F_ULOCK, 0);
...For the client, we'll need to call the doOAuth function through D-Bus.
...
else{
// Check if there is an input for sending through dbus
if (argc < 2) {
return 0;
}
// We already have a window running
// Send a signal through D-Bus
// Connect to the D-Bus login session bus
GError *error = NULL;
GDBusConnection *connection;
connection = g_bus_get_sync(G_BUS_TYPE_SESSION, NULL, &error);
if (error) {
g_print("Failed to connect to the D-Bus: %s\n", error->message);
g_error_free(error);
return 1;
}
// Create a new proxy object for the server's D-Bus interface
GDBusProxy *proxy;
proxy = g_dbus_proxy_new_sync(connection,
G_DBUS_PROXY_FLAGS_NONE,
NULL,
dbus_well_known_name,
dbus_object_path,
dbus_interface_name,
NULL,
&error);
if (error) {
g_print("Failed to create D-Bus proxy: %s\n", error->message);
g_error_free(error);
return 1;
}
// Call the oauth method on the server
g_dbus_proxy_call_sync(proxy,
dbus_method_name,
g_variant_new("(s)", argv[1]),
G_DBUS_CALL_FLAGS_NONE,
-1,
NULL,
&error);
if (error) {
g_print("Failed to call D-Bus method: %s\n", error->message);
g_error_free(error);
return 1;
}
// Clean up and exit
g_object_unref(proxy);
g_object_unref(connection);
return 0;
}
}
...Ok, we are done. Here is the result:
Please check out the sample on Github.