From nobody Mon Apr 29 00:19:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1548159380986629.7535150453973; Tue, 22 Jan 2019 04:16:20 -0800 (PST) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6987E81F09; Tue, 22 Jan 2019 12:16:18 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 97BC71C923; Tue, 22 Jan 2019 12:16:17 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 9FA431803395; Tue, 22 Jan 2019 12:16:15 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id x0MCGEte019842 for ; Tue, 22 Jan 2019 07:16:14 -0500 Received: by smtp.corp.redhat.com (Postfix) id 4C94D4142; Tue, 22 Jan 2019 12:16:14 +0000 (UTC) Received: from moe.brq.redhat.com (unknown [10.43.2.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id C899A5D9CB for ; Tue, 22 Jan 2019 12:16:11 +0000 (UTC) From: Michal Privoznik To: libvir-list@redhat.com Date: Tue, 22 Jan 2019 13:15:53 +0100 Message-Id: <1cbe4a4ceabddd38ddc80889dd437177c43f645c.1548159353.git.mprivozn@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] tools: Document completer callback X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Tue, 22 Jan 2019 12:16:19 +0000 (UTC) Content-Type: text/plain; charset="utf-8" Strictly speaking, this should go near vshCompleter typedef declaration. However, I find it more useful near actual completer implementations. Signed-off-by: Michal Privoznik Reviewed-by: John Ferlan --- tools/virsh-completer.c | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/tools/virsh-completer.c b/tools/virsh-completer.c index cfbfeae328..7a637a0cfa 100644 --- a/tools/virsh-completer.c +++ b/tools/virsh-completer.c @@ -35,6 +35,38 @@ #include "virxml.h" =20 =20 +/** + * A completer callback is a function that accepts three arguments: + * + * @ctl: virsh control structure + * @cmd: parsed input + * @flags: optional flags to alter completer's behaviour + * + * The @ctl contains connection to the daemon (should completer + * need it). Any completer that requires connection must check + * whether connection is still alive. + * + * The @cmd then holds parsed user input which might be missing + * some arguments (user is still typing the command), but may + * already contain important data. For instance if completer + * needs domain XML it may inspect @cmd to find --domain. Using + * existing wrappers is advised. If @cmd does not contain all + * necessary bits, completer might return sensible defaults (i.e. + * generic values not tailored to specific use case) or return + * NULL (i.e. no strings are offered to the user for completion). + * + * The @flags then contain .completer_flags value defined for + * each use or 0 if no .completer_flags were specified. If a + * completer is generic enough @flags can be used to alter it's + * behaviour. For instance, a completer to fetch names of domains + * can use @flags to return names of only domains in particular + * state that the command accepts. + * + * Under no circumstances a completer can output anything. Nor to + * stdout nor to stderr. This would harm the user experience. + */ + + char ** virshDomainNameCompleter(vshControl *ctl, const vshCmd *cmd ATTRIBUTE_UNUSED, --=20 2.19.2 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list