github.com/vmware/govmomi@v0.51.0/client.go (about)

     1  // © Broadcom. All Rights Reserved.
     2  // The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries.
     3  // SPDX-License-Identifier: Apache-2.0
     4  
     5  /*
     6  This package is the root package of the govmomi library.
     7  
     8  The library is structured as follows:
     9  
    10  # Package vim25
    11  
    12  The minimal usable functionality is available through the vim25 package.
    13  It contains subpackages that contain generated types, managed objects, and all
    14  available methods. The vim25 package is entirely independent of the other
    15  packages in the govmomi tree -- it has no dependencies on its peers.
    16  
    17  The vim25 package itself contains a client structure that is
    18  passed around throughout the entire library. It abstracts a session and its
    19  immutable state. See the vim25 package for more information.
    20  
    21  # Package session
    22  
    23  The session package contains an abstraction for the session manager that allows
    24  a user to login and logout. It also provides access to the current session
    25  (i.e. to determine if the user is in fact logged in)
    26  
    27  # Package object
    28  
    29  The object package contains wrappers for a selection of managed objects. The
    30  constructors of these objects all take a *vim25.Client, which they pass along
    31  to derived objects, if applicable.
    32  
    33  # Package govc
    34  
    35  The govc package contains the govc CLI. The code in this tree is not intended
    36  to be used as a library. Any functionality that govc contains that _could_ be
    37  used as a library function but isn't, _should_ live in a root level package.
    38  
    39  # Other packages
    40  
    41  Other packages, such as "event", "guest", or "license", provide wrappers for
    42  the respective subsystems. They are typically not needed in normal workflows so
    43  are kept outside the object package.
    44  */
    45  package govmomi
    46  
    47  import (
    48  	"context"
    49  	"net/url"
    50  
    51  	"github.com/vmware/govmomi/property"
    52  	"github.com/vmware/govmomi/session"
    53  	"github.com/vmware/govmomi/vim25"
    54  	"github.com/vmware/govmomi/vim25/soap"
    55  	"github.com/vmware/govmomi/vim25/types"
    56  )
    57  
    58  type Client struct {
    59  	*vim25.Client
    60  
    61  	SessionManager *session.Manager
    62  }
    63  
    64  // NewClient creates a new client from a URL. The client authenticates with the
    65  // server with username/password before returning if the URL contains user information.
    66  func NewClient(ctx context.Context, u *url.URL, insecure bool) (*Client, error) {
    67  	soapClient := soap.NewClient(u, insecure)
    68  	vimClient, err := vim25.NewClient(ctx, soapClient)
    69  	if err != nil {
    70  		return nil, err
    71  	}
    72  
    73  	c := &Client{
    74  		Client:         vimClient,
    75  		SessionManager: session.NewManager(vimClient),
    76  	}
    77  
    78  	// Only login if the URL contains user information.
    79  	if u.User != nil {
    80  		err = c.Login(ctx, u.User)
    81  		if err != nil {
    82  			return nil, err
    83  		}
    84  	}
    85  
    86  	return c, nil
    87  }
    88  
    89  // Login dispatches to the SessionManager.
    90  func (c *Client) Login(ctx context.Context, u *url.Userinfo) error {
    91  	return c.SessionManager.Login(ctx, u)
    92  }
    93  
    94  // Logout dispatches to the SessionManager.
    95  func (c *Client) Logout(ctx context.Context) error {
    96  	// Close any idle connections after logging out.
    97  	defer c.Client.CloseIdleConnections()
    98  	return c.SessionManager.Logout(ctx)
    99  }
   100  
   101  // PropertyCollector returns the session's default property collector.
   102  func (c *Client) PropertyCollector() *property.Collector {
   103  	return property.DefaultCollector(c.Client)
   104  }
   105  
   106  // RetrieveOne dispatches to the Retrieve function on the default property collector.
   107  func (c *Client) RetrieveOne(ctx context.Context, obj types.ManagedObjectReference, p []string, dst any) error {
   108  	return c.PropertyCollector().RetrieveOne(ctx, obj, p, dst)
   109  }
   110  
   111  // Retrieve dispatches to the Retrieve function on the default property collector.
   112  func (c *Client) Retrieve(ctx context.Context, objs []types.ManagedObjectReference, p []string, dst any) error {
   113  	return c.PropertyCollector().Retrieve(ctx, objs, p, dst)
   114  }
   115  
   116  // Wait dispatches to property.Wait.
   117  func (c *Client) Wait(ctx context.Context, obj types.ManagedObjectReference, ps []string, f func([]types.PropertyChange) bool) error {
   118  	return property.Wait(ctx, c.PropertyCollector(), obj, ps, f)
   119  }
   120  
   121  // IsVC returns true if we are connected to a vCenter
   122  func (c *Client) IsVC() bool {
   123  	return c.Client.IsVC()
   124  }